Ably Platform

Real-time messaging and pub/sub platform

ably.com/docs/api ↗

Version

1.1.0

OpenAPI

3.0.1

Endpoints

Schemas

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

Authentication

basic bearer

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](https://www.ably.io/documentation/rest-api/token-request-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
		optional

Request Body

{
  "content": {
    "application/json": {
      "schema": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/TokenRequest"
          },
          {
            "$ref": "#/components/schemas/SignedTokenRequest"
          }
        ]
      },
      "example": {
        "keyName": "YourKey.Name",
        "timestamp": "1559124196551",
        "capability": {
          "channel1": [
            "publish",
            "subscribe"
          ],
          "wildcard:channels:*": [
            "publish"
          ]
        }
      }
    }
  }
}

Responses

default

2XX OK

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
		optional
		optional
		optional
		optional
		optional

Responses

default Error

2XX OK

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
		optional
		optional
		optional
		optional
		optional

Responses

default

2XX OK

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
		optional

Request Body

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Message"
      }
    },
    "application/x-msgpack": {
      "schema": {
        "$ref": "#/components/schemas/Message"
      }
    },
    "application/x-www-form-urlencoded": {
      "schema": {
        "$ref": "#/components/schemas/Message"
      }
    }
  }
}

Responses

default

2XX OK

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
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

2XX OK

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
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

2XX OK

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

Request Body

{
  "content": {
    "application/json": {
      "schema": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "channel": {
                "type": "string",
                "description": "Channel name."
              },
              "deviceId": {
                "type": "string",
                "description": "Must be set when clientId is empty, cannot be used with clientId."
              }
            }
          },
          {
            "type": "object",
            "properties": {
              "channel": {
                "type": "string",
                "description": "Channel name."
              },
              "clientId": {
                "type": "string",
                "description": "Must be set when deviceId is empty, cannot be used with deviceId."
              }
            }
          }
        ]
      },
      "example": {
        "channel": "my:channel",
        "clientId": "myClientId"
      }
    },
    "application/x-msgpack": {
      "schema": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "channel": {
                "type": "string",
                "description": "Channel name."
              },
              "deviceId": {
                "type": "string",
                "description": "Must be set when clientId is empty, cannot be used with clientId."
              }
            }
          },
          {
            "type": "object",
            "properties": {
              "channel": {
                "type": "string",
                "description": "Channel name."
              },
              "clientId": {
                "type": "string",
                "description": "Must be set when deviceId is empty, cannot be used with deviceId."
              }
            }
          }
        ]
      },
      "example": {
        "channel": "my:channel",
        "clientId": "myClientId"
      }
    },
    "application/x-www-form-urlencoded": {
      "schema": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "channel": {
                "type": "string",
                "description": "Channel name."
              },
              "deviceId": {
                "type": "string",
                "description": "Must be set when clientId is empty, cannot be used with clientId."
              }
            }
          },
          {
            "type": "object",
            "properties": {
              "channel": {
                "type": "string",
                "description": "Channel name."
              },
              "clientId": {
                "type": "string",
                "description": "Must be set when deviceId is empty, cannot be used with deviceId."
              }
            }
          }
        ]
      },
      "example": {
        "channel": "my:channel",
        "clientId": "myClientId"
      }
    }
  }
}

Responses

default

2XX OK

POST /push/channelSubscriptions

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

Returns a paginated response of channel names.

operationId: getChannelsWithPushSubscribers

Responses

default

2XX OK

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
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

2XX OK

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
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

2XX OK

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

Request Body

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/DeviceDetails"
      }
    },
    "application/x-msgpack": {
      "schema": {
        "$ref": "#/components/schemas/DeviceDetails"
      }
    }
  }
}

Responses

default

2XX OK

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
		optional

Responses

default

2XX OK

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
		optional

Responses

default

2XX OK

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
		optional

Request Body

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/DeviceDetails"
      }
    },
    "application/x-msgpack": {
      "schema": {
        "$ref": "#/components/schemas/DeviceDetails"
      }
    },
    "application/x-www-form-urlencoded": {
      "schema": {
        "$ref": "#/components/schemas/DeviceDetails"
      }
    }
  }
}

Responses

default

2XX OK

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
		optional

Request Body

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/DeviceDetails"
      }
    },
    "application/x-msgpack": {
      "schema": {
        "$ref": "#/components/schemas/DeviceDetails"
      }
    },
    "application/x-www-form-urlencoded": {
      "schema": {
        "$ref": "#/components/schemas/DeviceDetails"
      }
    }
  }
}

Responses

default

2XX OK

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
		optional

Responses

default

2XX OK

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

Request Body

{
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "recipient"
        ],
        "properties": {
          "push": {
            "$ref": "#/components/schemas/Push"
          },
          "recipient": {
            "$ref": "#/components/schemas/Recipient"
          }
        }
      }
    },
    "application/x-msgpack": {
      "schema": {
        "type": "object",
        "required": [
          "recipient"
        ],
        "properties": {
          "push": {
            "$ref": "#/components/schemas/Push"
          },
          "recipient": {
            "$ref": "#/components/schemas/Recipient"
          }
        }
      }
    },
    "application/x-www-form-urlencoded": {
      "schema": {
        "type": "object",
        "required": [
          "recipient"
        ],
        "properties": {
          "push": {
            "$ref": "#/components/schemas/Push"
          },
          "recipient": {
            "$ref": "#/components/schemas/Recipient"
          }
        }
      }
    }
  }
}

Responses

default

2XX OK

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
		optional
		optional
		optional
		optional
unit	query	optional	string	Specifies the unit of aggregation in the returned results.

Responses

default

2XX OK

GET /stats

GET /time Get the service time

This returns the service time in milliseconds since the epoch.

operationId: getTime

Responses

default

2XX OK

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
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

2XX OK

GET /channels

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

Get metadata of a channel

operationId: getMetadataOfChannel

Parameters

Name	In	Required	Type	Description
		optional

Responses

default

200 OK

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
		optional
clientId	query	optional	string
connectionId	query	optional	string
limit	query	optional	integer

Responses

default

200 OK

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."
    }
  }
}