Platform API

Real-time messaging and pub/sub platform

Version

1.1.0

OpenAPI

3.0.1

Endpoints

Schemas

82

Quality

Updated

3 days ago

Infrastructure realtime messaging pubsub

Use this API in your AI agent

Query structured spec data via REST or MCP. Get exactly what your agent needs.

Get API Key

Server URLs

https://rest.ably.io

Endpoints

GET POST PUT PATCH DELETE

Authentication 1 endpoints

POST /keys/{keyName}/requestToken Request an access token

This is the means by which clients obtain access tokens to use the service. You can see how to construct an Ably TokenRequest in the Ably TokenRequest spec documentation, although we recommend you use an Ably SDK rather to create a TokenRequest, as the construction of a TokenRequest is complex. The resulting token response object contains the token properties as defined in Ably TokenRequest spec. Authentication is not required if using a Signed TokenRequest.

operationId: requestAccessToken

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
keyName	path	optional	string	The key name comprises of the app ID and key ID of an API key.

Request Body

application/json

Responses

default

Error

2XX

POST /keys/{keyName}/requestToken

History 2 endpoints

GET /channels/{channel_id}/messages Get message history for a channel

Get message history for a channel

operationId: getMessagesByChannel

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
channel_id	path	optional	string	The Channel’s ID.
start	query	optional	string	—
limit	query	optional	integer	—
end	query	optional	string	—
direction	query	optional	string	—

Responses

default

Error

2XX

GET /channels/{channel_id}/messages

GET /channels/{channel_id}/presence/history Get presence history of a channel

Get presence on a channel

operationId: getPresenceHistoryOfChannel

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
channel_id	path	optional	string	The Channel’s ID.
start	query	optional	string	—
limit	query	optional	integer	—
end	query	optional	string	—
direction	query	optional	string	—

Responses

default

Error

2XX

GET /channels/{channel_id}/presence/history

Publishing 1 endpoints

POST /channels/{channel_id}/messages Publish a message to a channel

Publish a message to the specified channel

operationId: publishMessagesToChannel

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
channel_id	path	optional	string	The Channel’s ID.

Request Body

application/json

schema Message

Property	Type	Required
id	string	optional
data	string	optional
name	string	optional
extras	object	optional
└ push	object	optional
└ fcm	object	optional
└ notification	object	optional
└ web	object	optional
└ notification	object	optional
└ apns	object	optional
└ notification	object	optional
└ data	string	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
clientId	string	optional
encoding	string	optional
timestamp	integer	optional
connectionId	string	optional

application/x-msgpack

schema Message

Property	Type	Required
id	string	optional
data	string	optional
name	string	optional
extras	object	optional
└ push	object	optional
└ fcm	object	optional
└ notification	object	optional
└ web	object	optional
└ notification	object	optional
└ apns	object	optional
└ notification	object	optional
└ data	string	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
clientId	string	optional
encoding	string	optional
timestamp	integer	optional
connectionId	string	optional

application/x-www-form-urlencoded

schema Message

Property	Type	Required
id	string	optional
data	string	optional
name	string	optional
extras	object	optional
└ push	object	optional
└ fcm	object	optional
└ notification	object	optional
└ web	object	optional
└ notification	object	optional
└ apns	object	optional
└ notification	object	optional
└ data	string	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
clientId	string	optional
encoding	string	optional
timestamp	integer	optional
connectionId	string	optional

Responses

default

Error

2XX

POST /channels/{channel_id}/messages

Push 13 endpoints

DELETE /push/channelSubscriptions Delete a registered device's update token

Delete a device details object.

operationId: deletePushDeviceDetails

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
channel	query	optional	string	Filter to restrict to subscriptions associated with that channel.
deviceId	query	optional	string	Must be set when clientId is empty, cannot be used with clientId.
clientId	query	optional	string	Must be set when deviceId is empty, cannot be used with deviceId.

Responses

default

Error

2XX

DELETE /push/channelSubscriptions

GET /push/channelSubscriptions List channel subscriptions

Get a list of push notification subscriptions to channels.

operationId: getPushSubscriptionsOnChannels

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
channel	query	optional	string	Filter to restrict to subscriptions associated with that channel.
deviceId	query	optional	string	Optional filter to restrict to devices associated with that deviceId. Cannot be used with clientId.
clientId	query	optional	string	Optional filter to restrict to devices associated with that clientId. Cannot be used with deviceId.
limit	query	optional	integer	The maximum number of records to return.

Responses

default

Error

2XX

GET /push/channelSubscriptions

POST /push/channelSubscriptions Subscribe a device to a channel

Subscribe either a single device or all devices associated with a client ID to receive push notifications from messages sent to a channel.

operationId: subscribePushDeviceToChannel

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like

Request Body

application/json

application/x-msgpack

application/x-www-form-urlencoded

Responses

default

Error

2XX

POST /push/channelSubscriptions

GET /push/channels List all channels with at least one subscribed device

Returns a paginated response of channel names.

operationId: getChannelsWithPushSubscribers

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like

Responses

default

Error

2XX

GET /push/channels

DELETE /push/deviceRegistrations Unregister matching devices for push notifications

Unregisters devices. All their subscriptions for receiving push notifications through channels will also be deleted.

operationId: unregisterAllPushDevices

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
deviceId	query	optional	string	Optional filter to restrict to devices associated with that deviceId. Cannot be used with clientId.
clientId	query	optional	string	Optional filter to restrict to devices associated with that clientId. Cannot be used with deviceId.

Responses

default

Error

2XX

DELETE /push/deviceRegistrations

GET /push/deviceRegistrations List devices registered for receiving push notifications

List of device details of devices registed for push notifications.

operationId: getRegisteredPushDevices

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
deviceId	query	optional	string	Optional filter to restrict to devices associated with that deviceId.
clientId	query	optional	string	Optional filter to restrict to devices associated with that clientId.
limit	query	optional	integer	The maximum number of records to return.

Responses

default

Error

2XX

GET /push/deviceRegistrations

POST /push/deviceRegistrations Register a device for receiving push notifications

Register a device’s details, including the information necessary to deliver push notifications to it. Requires “push-admin” capability.

operationId: registerPushDevice

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like

Request Body

application/json

schema DeviceDetails

Property	Type	Required
id	string	optional
clientId	string	optional
metadata	object	optional
platform	string	optional
formFactor	string	optional
push.state	string	optional
deviceSecret	string	optional
push.recipient	object	optional
└ clientId	string	optional
└ deviceId	string	optional
└ deviceToken	string	optional
└ transportType	string	optional
└ registrationToken	string	optional

application/x-msgpack

schema DeviceDetails

Property	Type	Required
id	string	optional
clientId	string	optional
metadata	object	optional
platform	string	optional
formFactor	string	optional
push.state	string	optional
deviceSecret	string	optional
push.recipient	object	optional
└ clientId	string	optional
└ deviceId	string	optional
└ deviceToken	string	optional
└ transportType	string	optional
└ registrationToken	string	optional

Responses

default

Error

2XX

POST /push/deviceRegistrations

DELETE /push/deviceRegistrations/{device_id} Unregister a single device for push notifications

Unregisters a single device by its device ID. All its subscriptions for receiving push notifications through channels will also be deleted.

operationId: unregisterPushDevice

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
device_id	path	optional	string	Device’s ID.

Responses

default

Error

2XX

DELETE /push/deviceRegistrations/{device_id}

GET /push/deviceRegistrations/{device_id} Get a device registration

Get the full details of a device.

operationId: getPushDeviceDetails

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
device_id	path	optional	string	Device’s ID.

Responses

default

Error

2XX

GET /push/deviceRegistrations/{device_id}

PATCH /push/deviceRegistrations/{device_id} Update a device registration

Specific attributes of an existing registration can be updated. Only clientId, metadata and push.recipient are mutable.

operationId: patchPushDeviceDetails

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
device_id	path	optional	string	Device’s ID.

Request Body

application/json

schema DeviceDetails

Property	Type	Required
id	string	optional
clientId	string	optional
metadata	object	optional
platform	string	optional
formFactor	string	optional
push.state	string	optional
deviceSecret	string	optional
push.recipient	object	optional
└ clientId	string	optional
└ deviceId	string	optional
└ deviceToken	string	optional
└ transportType	string	optional
└ registrationToken	string	optional

application/x-msgpack

schema DeviceDetails

Property	Type	Required
id	string	optional
clientId	string	optional
metadata	object	optional
platform	string	optional
formFactor	string	optional
push.state	string	optional
deviceSecret	string	optional
push.recipient	object	optional
└ clientId	string	optional
└ deviceId	string	optional
└ deviceToken	string	optional
└ transportType	string	optional
└ registrationToken	string	optional

application/x-www-form-urlencoded

schema DeviceDetails

Property	Type	Required
id	string	optional
clientId	string	optional
metadata	object	optional
platform	string	optional
formFactor	string	optional
push.state	string	optional
deviceSecret	string	optional
push.recipient	object	optional
└ clientId	string	optional
└ deviceId	string	optional
└ deviceToken	string	optional
└ transportType	string	optional
└ registrationToken	string	optional

Responses

default

Error

2XX

PATCH /push/deviceRegistrations/{device_id}

PUT /push/deviceRegistrations/{device_id} Update a device registration

Device registrations can be upserted (the existing registration is replaced entirely) with a PUT operation. Only clientId, metadata and push.recipient are mutable.

operationId: putPushDeviceDetails

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
device_id	path	optional	string	Device’s ID.

Request Body

application/json

schema DeviceDetails

Property	Type	Required
id	string	optional
clientId	string	optional
metadata	object	optional
platform	string	optional
formFactor	string	optional
push.state	string	optional
deviceSecret	string	optional
push.recipient	object	optional
└ clientId	string	optional
└ deviceId	string	optional
└ deviceToken	string	optional
└ transportType	string	optional
└ registrationToken	string	optional

application/x-msgpack

schema DeviceDetails

Property	Type	Required
id	string	optional
clientId	string	optional
metadata	object	optional
platform	string	optional
formFactor	string	optional
push.state	string	optional
deviceSecret	string	optional
push.recipient	object	optional
└ clientId	string	optional
└ deviceId	string	optional
└ deviceToken	string	optional
└ transportType	string	optional
└ registrationToken	string	optional

application/x-www-form-urlencoded

schema DeviceDetails

Property	Type	Required
id	string	optional
clientId	string	optional
metadata	object	optional
platform	string	optional
formFactor	string	optional
push.state	string	optional
deviceSecret	string	optional
push.recipient	object	optional
└ clientId	string	optional
└ deviceId	string	optional
└ deviceToken	string	optional
└ transportType	string	optional
└ registrationToken	string	optional

Responses

default

Error

2XX

PUT /push/deviceRegistrations/{device_id}

GET /push/deviceRegistrations/{device_id}/resetUpdateToken Reset a registered device's update token

Gets an updated device details object.

operationId: updatePushDeviceDetails

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
device_id	path	optional	string	Device’s ID.

Responses

default

Error

2XX

GET /push/deviceRegistrations/{device_id}/resetUpdateToken

POST /push/publish Publish a push notification to device(s)

A convenience endpoint to deliver a push notification payload to a single device or set of devices identified by their client identifier.

operationId: publishPushNotificationToDevices

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like

Request Body

application/json

Property	Type	Required
push	object	optional
└ fcm	object	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
└ web	object	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
└ apns	object	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
└ data	string	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
recipient	object	required
└ clientId	string	optional
└ deviceId	string	optional
└ deviceToken	string	optional
└ transportType	string	optional
└ registrationToken	string	optional

application/x-msgpack

Property	Type	Required
push	object	optional
└ fcm	object	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
└ web	object	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
└ apns	object	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
└ data	string	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
recipient	object	required
└ clientId	string	optional
└ deviceId	string	optional
└ deviceToken	string	optional
└ transportType	string	optional
└ registrationToken	string	optional

application/x-www-form-urlencoded

Property	Type	Required
push	object	optional
└ fcm	object	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
└ web	object	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
└ apns	object	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
└ data	string	optional
└ notification	object	optional
└ body	string	optional
└ icon	string	optional
└ sound	string	optional
└ title	string	optional
└ collapseKey	string	optional
recipient	object	required
└ clientId	string	optional
└ deviceId	string	optional
└ deviceToken	string	optional
└ transportType	string	optional
└ registrationToken	string	optional

Responses

default

Error

2XX

POST /push/publish

Stats 2 endpoints

GET /stats Retrieve usage statistics for an application

The Ably system can be queried to obtain usage statistics for a given application, and results are provided aggregated across all channels in use in the application in the specified period. Stats may be used to track usage against account quotas.

operationId: getStats

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
start	query	optional	string	—
limit	query	optional	integer	—
end	query	optional	string	—
direction	query	optional	string	—
unit	query	optional	string	Specifies the unit of aggregation in the returned results.

Responses

default

Error

2XX

GET /stats

GET /time Get the service time

This returns the service time in milliseconds since the epoch.

operationId: getTime

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like

Responses

default

Error

2XX

GET /time

Status 3 endpoints

GET /channels Enumerate all active channels of the application

Enumerate all active channels of the application

operationId: getMetadataOfAllChannels

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
limit	query	optional	integer	—
prefix	query	optional	string	Optionally limits the query to only those channels whose name starts with the given prefix
by	query	optional	string	optionally specifies whether to return just channel names (by=id) or ChannelDetails (by=value)

Responses

default

Error

2XX

GET /channels

GET /channels/{channel_id} Get metadata of a channel

Get metadata of a channel

operationId: getMetadataOfChannel

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
channel_id	path	optional	string	The Channel’s ID.

Responses

default

Error

200

GET /channels/{channel_id}

GET /channels/{channel_id}/presence Get presence of a channel

Get presence on a channel

operationId: getPresenceOfChannel

Parameters

Name	In	Required	Type	Description
X-Ably-Version	header	optional	string	The version of the API you wish to use.
format	query	optional	string	The response format you would like
channel_id	path	optional	string	The Channel’s ID.
clientId	query	optional	string	—
connectionId	query	optional	string	—
limit	query	optional	integer	—

Responses

default

Error

200

GET /channels/{channel_id}/presence

Schemas

object ChannelDetails

{
  "type": "object",
  "required": [
    "channelId"
  ],
  "properties": {
    "region": {
      "type": "string",
      "description": "In events relating to the activity of a channel in a specific region, this optionally identifies the region."
    },
    "status": {
      "$ref": "#/components/schemas/ChannelStatus"
    },
    "channelId": {
      "type": "string",
      "description": "The required name of the channel including any qualifier, if any."
    },
    "isGlobalMaster": {
      "type": "boolean",
      "description": "In events relating to the activity of a channel in a specific region, this optionally identifies whether or not that region is responsible for global coordination of the channel."
    }
  }
}

object ChannelStatus

{
  "type": "object",
  "required": [
    "isActive"
  ],
  "properties": {
    "isActive": {
      "type": "boolean",
      "description": "A required boolean value indicating whether the channel that is the subject of the event is active. For events indicating regional activity of a channel this indicates activity in that region, not global activity."
    },
    "occupancy": {
      "$ref": "#/components/schemas/Occupancy"
    }
  },
  "description": "A ChannelStatus instance."
}

object DeviceDetails

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the device generated by the device itself."
    },
    "clientId": {
      "type": "string",
      "description": "Optional trusted client identifier for the device."
    },
    "metadata": {
      "type": "object",
      "description": "Optional metadata object for this device. The metadata for a device may only be set by clients with push-admin privileges and will be used more extensively in the future with smart notifications."
    },
    "platform": {
      "enum": [
        "ios",
        "android"
      ],
      "type": "string",
      "description": "Platform of the push device."
    },
    "formFactor": {
      "enum": [
        "phone",
        "tablet",
        "desktop",
        "tv",
        "watch",
        "car",
        "embedded"
      ],
      "type": "string",
      "description": "Form factor of the push device."
    },
    "push.state": {
      "enum": [
        "Active",
        "Failing",
        "Failed"
      ],
      "type": "string",
      "readOnly": true,
      "description": "the current state of the push device."
    },
    "deviceSecret": {
      "type": "string",
      "description": "Secret value for the device."
    },
    "push.recipient": {
      "$ref": "#/components/schemas/Recipient"
    }
  }
}

object Error

{
  "type": "object",
  "properties": {
    "code": {
      "type": "integer",
      "description": "Error code."
    },
    "href": {
      "type": "string",
      "description": "Link to help with error."
    },
    "message": {
      "type": "string",
      "description": "Message explaining the error's cause."
    },
    "serverId": {
      "type": "string",
      "description": "Server ID with which error was encountered."
    },
    "statusCode": {
      "type": "integer",
      "description": "Status error code."
    }
  },
  "description": "Returned error from failed REST."
}

object Extras

{
  "type": "object",
  "properties": {
    "push": {
      "$ref": "#/components/schemas/Push"
    }
  },
  "description": "Extras object. Currently only allows for [push](https://www.ably.io/documentation/general/push/publish#channel-broadcast-example) extra."
}

object Message

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "readOnly": true,
      "description": "A Unique ID that can be specified by the publisher for [idempotent publishing](https://www.ably.io/documentation/rest/messages#idempotent)."
    },
    "data": {
      "type": "string",
      "description": "The string encoded payload, with the encoding specified below."
    },
    "name": {
      "type": "string",
      "description": "The event name, if provided."
    },
    "extras": {
      "$ref": "#/components/schemas/Extras"
    },
    "clientId": {
      "type": "string",
      "description": "The [client ID](https://www.ably.io/documentation/core-features/authentication#identified-clients) of the publisher of this message."
    },
    "encoding": {
      "type": "string",
      "description": "This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the data payload."
    },
    "timestamp": {
      "type": "integer",
      "format": "int64",
      "readOnly": true,
      "description": "Timestamp when the message was received by the Ably, as milliseconds since the epoch."
    },
    "connectionId": {
      "type": "string",
      "description": "The connection ID of the publisher of this message."
    }
  },
  "description": "Message object."
}

object Notification

{
  "type": "object",
  "properties": {
    "body": {
      "type": "string",
      "description": "Text below title on the expanded notification."
    },
    "icon": {
      "type": "string",
      "description": "Platform-specific icon for the notification."
    },
    "sound": {
      "type": "string",
      "description": "Platform-specific sound for the notification."
    },
    "title": {
      "type": "string",
      "description": "Title to display at the notification."
    },
    "collapseKey": {
      "type": "string",
      "description": "Platform-specific, used to group notifications together."
    }
  }
}

object Occupancy

{
  "type": "object",
  "properties": {
    "publishers": {
      "type": "integer",
      "description": "The number of connections attached to the channel that are authorised to publish."
    },
    "subscribers": {
      "type": "integer",
      "description": "The number of connections attached that are authorised to subscribe to messages."
    },
    "presenceMembers": {
      "type": "integer",
      "description": "The number of members currently entered into the presence channel."
    },
    "presenceConnections": {
      "type": "integer",
      "description": "The number of connections that are authorised to enter members into the presence channel."
    },
    "presenceSubscribers": {
      "type": "integer",
      "description": "The number of connections that are authorised to subscribe to presence messages."
    }
  },
  "description": "An Occupancy instance indicating the occupancy of a channel. For events indicating regional activity of a channel this indicates activity in that region, not global activity."
}

object PresenceMessage

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "readOnly": true,
      "description": "Unique ID assigned by Ably to this presence update."
    },
    "data": {
      "type": "string",
      "description": "The presence update payload, if provided."
    },
    "action": {
      "enum": [
        "ABSENT",
        "PRESENT",
        "ENTER",
        "LEAVE",
        "UPDATE"
      ],
      "type": "string",
      "readOnly": true,
      "description": "The event signified by a PresenceMessage."
    },
    "extras": {
      "$ref": "#/components/schemas/Extras"
    },
    "clientId": {
      "type": "string",
      "description": "The client ID of the publisher of this presence update."
    },
    "encoding": {
      "type": "string",
      "description": "This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the data payload."
    },
    "timestamp": {
      "type": "integer",
      "format": "int64",
      "readOnly": true,
      "description": "Timestamp when the presence update was received by Ably, as milliseconds since the epoch."
    },
    "connectionId": {
      "type": "string",
      "description": "The connection ID of the publisher of this presence update."
    }
  }
}

object Push

{
  "type": "object",
  "properties": {
    "fcm": {
      "type": "object",
      "properties": {
        "notification": {
          "$ref": "#/components/schemas/Notification"
        }
      },
      "description": "Extends and overrides generic values when delivering via GCM/FCM. [See examples](https://www.ably.io/documentation/general/push/publish#payload-structure)"
    },
    "web": {
      "type": "object",
      "properties": {
        "notification": {
          "$ref": "#/components/schemas/Notification"
        }
      },
      "description": "Extends and overrides generic values when delivering via web. [See examples](https://www.ably.io/documentation/general/push/publish#payload-structure)"
    },
    "apns": {
      "type": "object",
      "properties": {
        "notification": {
          "$ref": "#/components/schemas/Notification"
        }
      },
      "description": "Extends and overrides generic values when delivering via APNs. [See examples](https://www.ably.io/documentation/general/push/publish#payload-structure)"
    },
    "data": {
      "type": "string",
      "description": "Arbitrary [key-value string-to-string payload](https://www.ably.io/documentation/general/push/publish#channel-broadcast-example)."
    },
    "notification": {
      "$ref": "#/components/schemas/Notification"
    }
  }
}

object Recipient

{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "writeOnly": true,
      "description": "Client ID of recipient"
    },
    "deviceId": {
      "type": "string",
      "writeOnly": true,
      "description": "Client ID of recipient"
    },
    "deviceToken": {
      "type": "string",
      "description": "when using APNs, specifies the required device token."
    },
    "transportType": {
      "enum": [
        "apns",
        "fcm",
        "gcm"
      ],
      "type": "string",
      "description": "Defines which push platform is being used."
    },
    "registrationToken": {
      "type": "string",
      "description": "when using GCM or FCM, specifies the required registration token."
    }
  },
  "description": "Push recipient details for a device."
}

object SignedTokenRequest

{
  "allOf": [
    {
      "$ref": "#/components/schemas/TokenRequest"
    },
    {
      "type": "object",
      "required": [
        "mac"
      ],
      "properties": {
        "mac": {
          "type": "string",
          "description": "A signature, generated as an HMAC of each of the above components, using the key secret value."
        }
      }
    }
  ]
}

object TokenDetails

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The Ably Token."
    },
    "issued": {
      "type": "integer",
      "description": "Timestamp of token creation."
    },
    "expires": {
      "type": "integer",
      "description": "Timestamp of token expiration."
    },
    "keyName": {
      "type": "string",
      "description": "Name of the key used to create the token"
    },
    "capability": {
      "type": "string",
      "description": "Regular expression representation of the capabilities of the token."
    }
  }
}

object TokenRequest

{
  "type": "object",
  "required": [
    "keyName",
    "capability",
    "timestamp",
    "nonce"
  ],
  "properties": {
    "nonce": {
      "type": "string",
      "description": "An unquoted, un-escaped random string of at least 16 characters. Used to ensure the Ably TokenRequest cannot be reused."
    },
    "keyName": {
      "type": "string",
      "example": "xVLyHw.LMJZxw",
      "description": "Name of the key used for the TokenRequest. The keyName comprises of the app ID and key ID on an API Key."
    },
    "clientId": {
      "type": "string",
      "description": "The [client ID](https://www.ably.io/documentation/core-features/authentication#identified-clients) to be assosciated with the token. Can be set to * to allow for any client ID to be used."
    },
    "timestamp": {
      "type": "integer",
      "description": "Time of creation of the Ably TokenRequest."
    },
    "capability": {
      "type": "object",
      "example": {
        "channel1": [
          "publish",
          "subscribe"
        ]
      },
      "description": "The [capabilities](https://www.ably.io/documentation/core-features/authentication#capabilities-explained) (i.e. a set of channel names/namespaces and, for each, a set of operations) which should be a subset of the set of capabilities associated with the key specified in keyName."
    }
  }
}

Versions

Version	Endpoints	Schemas	Ingested	Status
1.1.0	22	14	2026-05-11	current
1.1.0	22	14	2026-04-16