Live Activity Schemas API

A Live Activity schema is a JSON Schema for one ActivityAttributes type in your app (for example FlightAttributes), covering both halves of the card: the ContentState fields that change while the activity runs, and the fields fixed for its whole lifetime. Publish a schema so a journey’s Live Activity element can build named fields for both halves from it, instead of a raw JSON editor and a free-form field list. The card and its layout are still built in your app’s code. The schema only describes the data a journey fills in.

This API is for developers integrating Live Activities. See the iOS Live Activities API for starting and updating activities themselves.

Writing a schema

attributesType is the name of the Swift type that conforms to ActivityAttributes in your app. Pushwoosh doesn’t read your code or validate the name against it — it’s just the string the API stores and the string you pass to startLiveActivity’s attributes-type field.

jsonSchema covers both halves of that type, in two separate places:

• The ContentState fields, the ones that change while the activity runs, like a flight’s gate, status, or ETA, go in the schema’s root properties.
• The ActivityAttributes fields, fixed for the activity’s whole lifetime and set once when it starts, like a flight number, go in a separate attributes section, with its own properties and an optional required list.

The attributes section is optional. Without it, ActivityAttributes fields stay a free field name/value list on the Live Activity element instead of named fields. You always pass the actual attribute values through live_activity.attributes on startLiveActivity — the schema only declares their names, types, and which ones are required.

Example

struct FlightAttributes: ActivityAttributes {
    struct ContentState: Codable, Hashable {
        var gate: String
        var status: String
        var estimatedTime: String
    }

    var flightNumber: String
}

flightNumber lives in ActivityAttributes. gate, status, and estimatedTime live in ContentState. Publish both halves as the schema for attributesType: "FlightAttributes":

{
  "type": "object",
  "properties": {
    "gate": { "type": "string" },
    "status": { "type": "string" },
    "estimatedTime": { "type": "string" }
  },
  "attributes": {
    "properties": {
      "flightNumber": { "type": "string" }
    },
    "required": ["flightNumber"]
  }
}

required inside attributes makes flightNumber mandatory on the Live Activity element’s Start step: leaving it blank there is rejected. The root properties for ContentState fields has no such list. A journey is never required to fill gate, status, or estimatedTime.

Once published, a journey’s Live Activity element reads this shape to offer named fields for gate, status, and estimatedTime in Card content, instead of a raw content-state editor. The same happens for flightNumber in Card attributes, instead of a free field name/value list.

See Conventions below for the format and immutability rules that apply to jsonSchema, and Managing schemas in the Control Panel at the end of this page for the same actions without calling the API directly.

Base URL

https://rpc-api.svc-nue.pushwoosh.com

Authentication

Every request must include an Authorization header with your Server API token:

Authorization: Api YOUR_API_TOKEN

Conventions

• Field naming is asymmetric. Requests accept both lowerCamelCase and the proto name. Responses always come back with the proto field names, in snake_case (attributes_type, json_schema) — the examples below use that casing.
• Versions are immutable. A published version can’t be edited — there is no Update method. Publishing again with the same attributesType and version fails with AlreadyExists. A widget change is always a new version. Omit version on Create to publish the next free one for that attributesType.
• jsonSchema format: must be a JSON object with "type": "object", up to 64 KB. null, a number, a bare string, or an object missing "type": "object" are all rejected, because the form Pushwoosh builds needs named fields, which only an object schema has. The optional attributes section, when present, must itself be an object with its own properties and, optionally, a required array that only names fields declared in attributes.properties. A field name can’t appear in both properties and attributes.properties.

Endpoints

Method	Path	Description
GET	/api/live_activity_schemas	List an application’s schemas
GET	/api/live_activity_schemas/{attributesType}/{version}	Get one schema version
POST	/api/live_activity_schemas	Publish a new schema version
DELETE	/api/live_activity_schemas/{attributesType}/{version}	Delete a schema version

List

Lists every attributesType an application has published schemas for, with all their versions, newest version first.

GET /api/live_activity_schemas

Query parameters

Parameter	Type	Required	Description
application	string	Yes	The application code to list schemas for.
attributesType	string	No	Restrict the list to one ActivityAttributes type.

Response example

{
  "schemas": [
    {
      "application": "XXXXX-XXXXX",
      "attributes_type": "FlightAttributes",
      "version": 2,
      "json_schema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"}},\"attributes\":{\"properties\":{\"flightNumber\":{\"type\":\"string\"}},\"required\":[\"flightNumber\"]}}",
      "created": "2026-09-01T10:00:00Z",
      "updated": "2026-09-01T10:00:00Z"
    },
    {
      "application": "XXXXX-XXXXX",
      "attributes_type": "FlightAttributes",
      "version": 1,
      "json_schema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}}}",
      "created": "2026-08-15T10:00:00Z",
      "updated": "2026-08-15T10:00:00Z"
    }
  ]
}

Get

Returns one schema version.

GET /api/live_activity_schemas/{attributesType}/{version}

Path parameters

Parameter	Type	Required	Description
attributesType	string	Yes	Name of the ActivityAttributes type.
version	integer	Yes	Schema version.

Query parameters

Parameter	Type	Required	Description
application	string	Yes	The application code the schema belongs to.

Response

Returns { "schema": { ... } }, the schema object shown in List above.

Create

Publishes a new schema version for an attributesType. Returns the created schema, including the version it was assigned.

POST /api/live_activity_schemas

Request body

Parameter	Type	Required	Description
application	string	Yes	The application code to publish the schema in.
attributesType	string	Yes	Name of the ActivityAttributes type declared in your app.
jsonSchema	string	Yes	JSON Schema of both ContentState and attributes. See Writing a schema above.
version	integer	No	Version to publish. Omit to get the next free version for this attributesType.

Request example

{
  "application": "XXXXX-XXXXX",
  "attributesType": "FlightAttributes",
  "jsonSchema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}},\"attributes\":{\"properties\":{\"flightNumber\":{\"type\":\"string\"}},\"required\":[\"flightNumber\"]}}"
}

Response

Returns { "schema": { ... } }, the created schema object.

Caution

Publishing an attributesType/version pair that already exists fails with AlreadyExists — versions are immutable, so there’s no way to overwrite one. Publish without version to get the next one instead.

Delete

Permanently deletes one schema version.

DELETE /api/live_activity_schemas/{attributesType}/{version}

Path parameters

Parameter	Type	Required	Description
attributesType	string	Yes	Name of the ActivityAttributes type.
version	integer	Yes	Schema version to delete.

Query parameters

Parameter	Type	Required	Description
application	string	Yes	The application code the schema belongs to.

Response

Returns an empty object on success.

Danger

This cannot be undone. A journey’s Live Activity element built against the deleted version keeps its already-saved content and attribute values. It just loses the form hints for both from then on: content falls back to a raw JSON editor, and attributes fall back to a free field name/value list.

Error responses

HTTP status	Meaning
400 Bad Request	Invalid argument: a required field is missing, jsonSchema fails the format rule above (including an invalid attributes section), or jsonSchema exceeds 64 KB.
401 Unauthorized	Missing or invalid Authorization header.
403 Forbidden	The application does not belong to the caller’s account.
404 Not Found	The application, or the attributesType/version pair, was not found.
409 Conflict	Create was called with an attributesType/version pair that already exists (AlreadyExists on the wire).
500 Internal Server Error	Unexpected server-side failure.

Managing schemas in the Control Panel

The Control Panel offers the same actions as the API without calling it directly: list versions by type, publish a new version, view a version’s JSON, and delete a version (with a confirmation, since deletion is permanent). See iOS Live Activity schemas configuration for the click path.