Platform API
The REST API specification(https://www
COMMUNITYBEARER0 INSTALLS
OpenAPI Specificationv3.0
{
"openapi": "3.0.1",
"servers": [
{
"url": "https://rest.ably.io"
}
],
"info": {
"contact": {
"email": "support@ably.io",
"name": "Ably Support",
"url": "https://www.ably.io/contact",
"x-twitter": "ablyrealtime"
},
"description": "The [REST API specification](https://www.ably.io/documentation/rest-api) for Ably.",
"title": "Platform API",
"version": "1.1.0",
"x-apisguru-categories": [
"cloud"
],
"x-logo": {
"url": "https://api.apis.guru/v2/cache/logo/https_twitter_com_ablyrealtime_profile_image.svg"
},
"x-origin": [
{
"format": "openapi",
"url": "https://raw.githubusercontent.com/ably/open-specs/main/definitions/platform-v1.yaml",
"version": "3.0"
}
],
"x-providerName": "ably.io",
"x-serviceName": "platform"
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"paths": {
"/channels": {
"get": {
"description": "Enumerate all active channels of the application",
"operationId": "getMetadataOfAllChannels",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"type": "integer"
}
},
{
"description": "Optionally limits the query to only those channels whose name starts with the given prefix",
"in": "query",
"name": "prefix",
"schema": {
"type": "string"
}
},
{
"description": "optionally specifies whether to return just channel names (by=id) or ChannelDetails (by=value)",
"in": "query",
"name": "by",
"schema": {
"enum": [
"value",
"id"
],
"type": "string"
}
}
],
"responses": {
"2XX": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"items": {
"$ref": "#/components/schemas/ChannelDetails"
},
"type": "array"
},
{
"items": {
"type": "string"
},
"type": "array"
}
]
}
},
"application/x-msgpack": {
"schema": {
"oneOf": [
{
"items": {
"$ref": "#/components/schemas/ChannelDetails"
},
"type": "array"
},
{
"items": {
"type": "string"
},
"type": "array"
}
]
}
},
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "OK",
"headers": {
"link": {
"$ref": "#/components/headers/Link"
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Enumerate all active channels of the application",
"tags": [
"Status"
]
},
"parameters": [
{
"$ref": "#/components/parameters/versionHeader"
},
{
"$ref": "#/components/parameters/responseFormat"
}
]
},
"/channels/{channel_id}": {
"get": {
"description": "Get metadata of a channel",
"operationId": "getMetadataOfChannel",
"parameters": [
{
"$ref": "#/components/parameters/channelId"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelDetails"
}
}
},
"description": "OK",
"headers": {
"x-ably-serverid": {
"$ref": "#/components/headers/ServerId"
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Get metadata of a channel",
"tags": [
"Status"
]
},
"parameters": [
{
"$ref": "#/components/parameters/versionHeader"
},
{
"$ref": "#/components/parameters/responseFormat"
}
]
},
"/channels/{channel_id}/messages": {
"get": {
"description": "Get message history for a channel",
"operationId": "getMessagesByChannel",
"parameters": [
{
"$ref": "#/components/parameters/channelId"
},
{
"$ref": "#/components/parameters/filterStart"
},
{
"$ref": "#/components/parameters/filterLimit"
},
{
"$ref": "#/components/parameters/filterEnd"
},
{
"$ref": "#/components/parameters/filterDirection"
}
],
"responses": {
"2XX": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/Message"
},
"type": "array"
}
},
"application/x-msgpack": {
"schema": {
"items": {
"$ref": "#/components/schemas/Message"
},
"type": "array"
}
},
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "OK",
"headers": {
"link": {
"$ref": "#/components/headers/Link"
},
"x-ably-serverid": {
"$ref": "#/components/headers/ServerId"
}
}
},
"default": {
"description": "Error",
"headers": {
"x-ably-errorcode": {
"$ref": "#/components/headers/ErrorCode"
},
"x-ably-errormessage": {
"$ref": "#/components/headers/ErrorMessage"
},
"x-ably-serverid": {
"$ref": "#/components/headers/ServerId"
}
}
}
},
"summary": "Get message history for a channel",
"tags": [
"History"
]
},
"parameters": [
{
"$ref": "#/components/parameters/versionHeader"
},
{
"$ref": "#/components/parameters/responseFormat"
}
],
"post": {
"description": "Publish a message to the specified channel",
"operationId": "publishMessagesToChannel",
"parameters": [
{
"$ref": "#/components/parameters/channelId"
}
],
"requestBody": {
"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": {
"2XX": {
"content": {
"application/json": {
"schema": {
"properties": {
"channel": {
"type": "string"
},
"messageId": {
"type": "string"
}
},
"type": "object"
}
},
"application/x-msgpack": {
"schema": {
"properties": {
"channel": {
"type": "string"
},
"messageId": {
"type": "string"
}
},
"type": "object"
}
},
"text/html": {
"schema": {
"properties": {
"channel": {
"type": "string"
},
"messageId": {
"type": "string"
}
},
"type": "object"
}
}
},
"description": "OK",
"headers": {
"x-ably-serverid": {
"$ref": "#/components/headers/ServerId"
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Publish a message to a channel",
"tags": [
"Publishing"
]
}
},
"/channels/{channel_id}/presence": {
"get": {
"description": "Get presence on a channel",
"operationId": "getPresenceOfChannel",
"parameters": [
{
"$ref": "#/components/parameters/channelId"
},
{
"in": "query",
"name": "clientId",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "connectionId",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/PresenceMessage"
},
"type": "array"
}
},
"application/x-msgpack": {
"schema": {
"items": {
"$ref": "#/components/schemas/PresenceMessage"
},
"type": "array"
}
},
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "OK",
"headers": {
"link": {
"$ref": "#/components/headers/Link"
},
"x-ably-serverid": {
"$ref": "#/components/headers/ServerId"
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Get presence of a channel",
"tags": [
"Status"
]
},
"parameters": [
{
"$ref": "#/components/parameters/versionHeader"
},
{
"$ref": "#/components/parameters/responseFormat"
}
]
},
"/channels/{channel_id}/presence/history": {
"get": {
"description": "Get presence on a channel",
"operationId": "getPresenceHistoryOfChannel",
"parameters": [
{
"$ref": "#/components/parameters/channelId"
},
{
"$ref": "#/components/parameters/filterStart"
},
{
"$ref": "#/components/parameters/filterLimit"
},
{
"$ref": "#/components/parameters/filterEnd"
},
{
"$ref": "#/components/parameters/filterDirection"
}
],
"responses": {
"2XX": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/PresenceMessage"
},
"type": "array"
}
},
"application/x-msgpack": {
"schema": {
"items": {
"$ref": "#/components/schemas/PresenceMessage"
},
"type": "array"
}
},
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "OK",
"headers": {
"link": {
"$ref": "#/components/headers/Link"
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Get presence history of a channel",
"tags": [
"History"
]
},
"parameters": [
{
"$ref": "#/components/parameters/versionHeader"
},
{
"$ref": "#/components/parameters/responseFormat"
}
]
},
"/keys/{keyName}/requestToken": {
"parameters": [
{
"$ref": "#/components/parameters/versionHeader"
},
{
"$ref": "#/components/parameters/responseFormat"
}
],
"post": {
"description": "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": [
{
"$ref": "#/components/parameters/key_name"
}
],
"requestBody": {
"content": {
"application/json": {
"example": {
"capability": {
"channel1": [
"publish",
"subscribe"
],
"wildcard:channels:*": [
"publish"
]
},
"keyName": "YourKey.Name",
"timestamp": "1559124196551"
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/TokenRequest"
},
{
"$ref": "#/components/schemas/SignedTokenRequest"
}
]
}
}
}
},
"responses": {
"2XX": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenDetails"
}
},
"application/x-msgpack": {
"schema": {
"$ref": "#/components/schemas/TokenDetails"
}
}
},
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Request an access token",
"tags": [
"Authentication"
]
}
},
"/push/channelSubscriptions": {
"delete": {
"description": "Delete a device details object.",
"operationId": "deletePushDeviceDetails",
"parameters": [
{
"description": "Filter to restrict to subscriptions associated with that channel.",
"in": "query",
"name": "channel",
"schema": {
"type": "string"
}
},
{
"description": "Must be set when clientId is empty, cannot be used with clientId.",
"in": "query",
"name": "deviceId",
"schema": {
"type": "string"
}
},
{
"description": "Must be set when deviceId is empty, cannot be used with deviceId.",
"in": "query",
"name": "clientId",
"schema": {
"type": "string"
}
}
],
"responses": {
"2XX": {
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Delete a registered device's update token",
"tags": [
"Push"
]
},
"get": {
"description": "Get a list of push notification subscriptions to channels.",
"operationId": "getPushSubscriptionsOnChannels",
"parameters": [
{
"description": "Filter to restrict to subscriptions associated with that channel.",
"in": "query",
"name": "channel",
"schema": {
"type": "string"
}
},
{
"description": "Optional filter to restrict to devices associated with that deviceId. Cannot be used with clientId.",
"in": "query",
"name": "deviceId",
"schema": {
"type": "string"
}
},
{
"description": "Optional filter to restrict to devices associated with that clientId. Cannot be used with deviceId.",
"in": "query",
"name": "clientId",
"schema": {
"type": "string"
}
},
{
"description": "The maximum number of records to return.",
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"maximum": 1000,
"type": "integer"
}
}
],
"responses": {
"2XX": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
}
},
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "List channel subscriptions",
"tags": [
"Push"
]
},
"parameters": [
{
"$ref": "#/components/parameters/versionHeader"
},
{
"$ref": "#/components/parameters/responseFormat"
}
],
"post": {
"description": "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",
"requestBody": {
"content": {
"application/json": {
"example": {
"channel": "my:channel",
"clientId": "myClientId"
},
"schema": {
"oneOf": [
{
"properties": {
"channel": {
"description": "Channel name.",
"type": "string"
},
"deviceId": {
"description": "Must be set when clientId is empty, cannot be used with clientId.",
"type": "string"
}
},
"type": "object"
},
{
"properties": {
"channel": {
"description": "Channel name.",
"type": "string"
},
"clientId": {
"description": "Must be set when deviceId is empty, cannot be used with deviceId.",
"type": "string"
}
},
"type": "object"
}
]
}
},
"application/x-msgpack": {
"example": {
"channel": "my:channel",
"clientId": "myClientId"
},
"schema": {
"oneOf": [
{
"properties": {
"channel": {
"description": "Channel name.",
"type": "string"
},
"deviceId": {
"description": "Must be set when clientId is empty, cannot be used with clientId.",
"type": "string"
}
},
"type": "object"
},
{
"properties": {
"channel": {
"description": "Channel name.",
"type": "string"
},
"clientId": {
"description": "Must be set when deviceId is empty, cannot be used with deviceId.",
"type": "string"
}
},
"type": "object"
}
]
}
},
"application/x-www-form-urlencoded": {
"example": {
"channel": "my:channel",
"clientId": "myClientId"
},
"schema": {
"oneOf": [
{
"properties": {
"channel": {
"description": "Channel name.",
"type": "string"
},
"deviceId": {
"description": "Must be set when clientId is empty, cannot be used with clientId.",
"type": "string"
}
},
"type": "object"
},
{
"properties": {
"channel": {
"description": "Channel name.",
"type": "string"
},
"clientId": {
"description": "Must be set when deviceId is empty, cannot be used with deviceId.",
"type": "string"
}
},
"type": "object"
}
]
}
}
}
},
"responses": {
"2XX": {
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Subscribe a device to a channel",
"tags": [
"Push"
]
}
},
"/push/channels": {
"get": {
"description": "Returns a paginated response of channel names.",
"operationId": "getChannelsWithPushSubscribers",
"responses": {
"2XX": {
"content": {
"application/json": {
"schema": {
"items": {
"type": "string"
},
"type": "array"
}
},
"application/x-msgpack": {
"schema": {
"items": {
"type": "string"
},
"type": "array"
}
},
"text/html": {
"schema": {
"items": {
"type": "string"
},
"type": "array"
}
}
},
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "List all channels with at least one subscribed device",
"tags": [
"Push"
]
},
"parameters": [
{
"$ref": "#/components/parameters/versionHeader"
},
{
"$ref": "#/components/parameters/responseFormat"
}
]
},
"/push/deviceRegistrations": {
"delete": {
"description": "Unregisters devices. All their subscriptions for receiving push notifications through channels will also be deleted.",
"operationId": "unregisterAllPushDevices",
"parameters": [
{
"description": "Optional filter to restrict to devices associated with that deviceId. Cannot be used with clientId.",
"in": "query",
"name": "deviceId",
"schema": {
"type": "string"
}
},
{
"description": "Optional filter to restrict to devices associated with that clientId. Cannot be used with deviceId.",
"in": "query",
"name": "clientId",
"schema": {
"type": "string"
}
}
],
"responses": {
"2XX": {
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Unregister matching devices for push notifications",
"tags": [
"Push"
]
},
"get": {
"description": "List of device details of devices registed for push notifications.",
"operationId": "getRegisteredPushDevices",
"parameters": [
{
"description": "Optional filter to restrict to devices associated with that deviceId.",
"in": "query",
"name": "deviceId",
"schema": {
"type": "string"
}
},
{
"description": "Optional filter to restrict to devices associated with that clientId.",
"in": "query",
"name": "clientId",
"schema": {
"type": "string"
}
},
{
"description": "The maximum number of records to return.",
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"maximum": 1000,
"type": "integer"
}
}
],
"responses": {
"2XX": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
},
"application/x-msgpack": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
},
"text/html": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
}
},
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "List devices registered for receiving push notifications",
"tags": [
"Push"
]
},
"parameters": [
{
"$ref": "#/components/parameters/versionHeader"
},
{
"$ref": "#/components/parameters/responseFormat"
}
],
"post": {
"description": "Register a device’s details, including the information necessary to deliver push notifications to it. Requires \"push-admin\" capability.",
"operationId": "registerPushDevice",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
},
"application/x-msgpack": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
}
}
},
"responses": {
"2XX": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
},
"application/x-msgpack": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
},
"text/html": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
}
},
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Register a device for receiving push notifications",
"tags": [
"Push"
]
}
},
"/push/deviceRegistrations/{device_id}": {
"delete": {
"description": "Unregisters a single device by its device ID. All its subscriptions for receiving push notifications through channels will also be deleted.",
"operationId": "unregisterPushDevice",
"parameters": [
{
"$ref": "#/components/parameters/deviceId"
}
],
"responses": {
"2XX": {
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Unregister a single device for push notifications",
"tags": [
"Push"
]
},
"get": {
"description": "Get the full details of a device.",
"operationId": "getPushDeviceDetails",
"parameters": [
{
"$ref": "#/components/parameters/deviceId"
}
],
"responses": {
"2XX": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
},
"application/x-msgpack": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
},
"text/html": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
}
},
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Get a device registration",
"tags": [
"Push"
]
},
"parameters": [
{
"$ref": "#/components/parameters/versionHeader"
},
{
"$ref": "#/components/parameters/responseFormat"
}
],
"patch": {
"description": "Specific attributes of an existing registration can be updated. Only clientId, metadata and push.recipient are mutable.",
"operationId": "patchPushDeviceDetails",
"parameters": [
{
"$ref": "#/components/parameters/deviceId"
}
],
"requestBody": {
"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": {
"2XX": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
},
"application/x-msgpack": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
},
"text/html": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
}
},
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Update a device registration",
"tags": [
"Push"
]
},
"put": {
"description": "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": [
{
"$ref": "#/components/parameters/deviceId"
}
],
"requestBody": {
"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": {
"2XX": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
},
"application/x-msgpack": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
},
"text/html": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
}
},
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Update a device registration",
"tags": [
"Push"
]
}
},
"/push/deviceRegistrations/{device_id}/resetUpdateToken": {
"get": {
"description": "Gets an updated device details object.",
"operationId": "updatePushDeviceDetails",
"parameters": [
{
"$ref": "#/components/parameters/deviceId"
}
],
"responses": {
"2XX": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
},
"application/x-msgpack": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
},
"text/html": {
"schema": {
"$ref": "#/components/schemas/DeviceDetails"
}
}
},
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Reset a registered device's update token",
"tags": [
"Push"
]
},
"parameters": [
{
"$ref": "#/components/parameters/versionHeader"
},
{
"$ref": "#/components/parameters/responseFormat"
}
]
},
"/push/publish": {
"parameters": [
{
"$ref": "#/components/parameters/versionHeader"
},
{
"$ref": "#/components/parameters/responseFormat"
}
],
"post": {
"description": "A convenience endpoint to deliver a push notification payload to a single device or set of devices identified by their client identifier.",
"operationId": "publishPushNotificationToDevices",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"push": {
"$ref": "#/components/schemas/Push"
},
"recipient": {
"$ref": "#/components/schemas/Recipient"
}
},
"required": [
"recipient"
],
"type": "object"
}
},
"application/x-msgpack": {
"schema": {
"properties": {
"push": {
"$ref": "#/components/schemas/Push"
},
"recipient": {
"$ref": "#/components/schemas/Recipient"
}
},
"required": [
"recipient"
],
"type": "object"
}
},
"application/x-www-form-urlencoded": {
"schema": {
"properties": {
"push": {
"$ref": "#/components/schemas/Push"
},
"recipient": {
"$ref": "#/components/schemas/Recipient"
}
},
"required": [
"recipient"
],
"type": "object"
}
}
}
},
"responses": {
"2XX": {
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Publish a push notification to device(s)",
"tags": [
"Push"
]
}
},
"/stats": {
"get": {
"description": "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": [
{
"$ref": "#/components/parameters/filterStart"
},
{
"$ref": "#/components/parameters/filterLimit"
},
{
"$ref": "#/components/parameters/filterEnd"
},
{
"$ref": "#/components/parameters/filterDirection"
},
{
"description": "Specifies the unit of aggregation in the returned results.",
"in": "query",
"name": "unit",
"schema": {
"default": "minute",
"enum": [
"minute",
"hour",
"day",
"month"
],
"type": "string"
}
}
],
"responses": {
"2XX": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
},
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"summary": "Retrieve usage statistics for an application",
"tags": [
"Stats"
]
},
"parameters": [
{
"$ref": "#/components/parameters/versionHeader"
},
{
"$ref": "#/components/parameters/responseFormat"
}
]
},
"/time": {
"get": {
"description": "This returns the service time in milliseconds since the epoch.",
"operationId": "getTime",
"responses": {
"2XX": {
"content": {
"application/json": {
"schema": {
"items": {
"type": "integer"
},
"type": "array"
}
},
"application/x-msgpack": {
"schema": {
"items": {
"type": "integer"
},
"type": "array"
}
},
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "OK"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"security": [],
"summary": "Get the service time",
"tags": [
"Stats"
]
},
"parameters": [
{
"$ref": "#/components/parameters/versionHeader"
},
{
"$ref": "#/components/parameters/responseFormat"
}
]
}
},
"components": {
"headers": {
"ErrorCode": {
"description": "The error code.",
"schema": {
"type": "integer"
}
},
"ErrorMessage": {
"description": "The error message.",
"schema": {
"type": "string"
}
},
"Link": {
"description": "Links to related resources, in the format defined by [RFC 5988](https://tools.ietf.org/html/rfc5988#section-5). This will potentially include a link with relation type `next`, `first`, and `current`, where appropiate.",
"required": true,
"schema": {
"pattern": "(<(.*)?>; rel=\\\"(first|current|last)?\\\",)*(<(.*)?>; rel=\\\"(first|current|last)?\\\")+",
"type": "string"
}
},
"ServerId": {
"description": "The ID for the server communicated with.",
"required": true,
"schema": {
"type": "string"
}
}
},
"parameters": {
"channelId": {
"description": "The [Channel's ID](https://www.ably.io/documentation/rest/channels).",
"in": "path",
"name": "channel_id",
"required": true,
"schema": {
"type": "string"
}
},
"deviceId": {
"description": "Device's ID.",
"in": "path",
"name": "device_id",
"required": true,
"schema": {
"type": "string"
}
},
"filterDirection": {
"in": "query",
"name": "direction",
"schema": {
"default": "backwards",
"enum": [
"forwards",
"backwards"
],
"type": "string"
}
},
"filterEnd": {
"in": "query",
"name": "end",
"schema": {
"default": "now",
"type": "string"
}
},
"filterLimit": {
"in": "query",
"name": "limit",
"schema": {
"default": "100",
"type": "integer"
}
},
"filterStart": {
"in": "query",
"name": "start",
"schema": {
"type": "string"
}
},
"key_name": {
"description": "The [key name](https://www.ably.io/documentation/rest-api/token-request-spec#api-key-format) comprises of the app ID and key ID of an API key.",
"in": "path",
"name": "keyName",
"required": true,
"schema": {
"type": "string"
}
},
"responseFormat": {
"description": "The response format you would like",
"in": "query",
"name": "format",
"schema": {
"enum": [
"json",
"jsonp",
"msgpack",
"html"
],
"type": "string"
}
},
"versionHeader": {
"description": "The version of the API you wish to use.",
"in": "header",
"name": "X-Ably-Version",
"schema": {
"type": "string"
}
}
},
"responses": {
"Error": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
},
"application/x-msgpack": {
"schema": {
"$ref": "#/components/schemas/Error"
}
},
"text/html": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Error",
"headers": {
"x-ably-errorcode": {
"$ref": "#/components/headers/ErrorCode"
},
"x-ably-errormessage": {
"$ref": "#/components/headers/ErrorMessage"
},
"x-ably-serverid": {
"$ref": "#/components/headers/ServerId"
}
}
}
},
"schemas": {
"ChannelDetails": {
"properties": {
"channelId": {
"description": "The required name of the channel including any qualifier, if any.",
"type": "string"
},
"isGlobalMaster": {
"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.",
"type": "boolean"
},
"region": {
"description": "In events relating to the activity of a channel in a specific region, this optionally identifies the region.",
"type": "string"
},
"status": {
"$ref": "#/components/schemas/ChannelStatus"
}
},
"required": [
"channelId"
],
"type": "object"
},
"ChannelStatus": {
"description": "A ChannelStatus instance.",
"properties": {
"isActive": {
"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.",
"type": "boolean"
},
"occupancy": {
"$ref": "#/components/schemas/Occupancy"
}
},
"required": [
"isActive"
],
"type": "object"
},
"DeviceDetails": {
"properties": {
"clientId": {
"description": "Optional trusted client identifier for the device.",
"type": "string"
},
"deviceSecret": {
"description": "Secret value for the device.",
"type": "string"
},
"formFactor": {
"description": "Form factor of the push device.",
"enum": [
"phone",
"tablet",
"desktop",
"tv",
"watch",
"car",
"embedded"
],
"type": "string"
},
"id": {
"description": "Unique identifier for the device generated by the device itself.",
"type": "string"
},
"metadata": {
"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.",
"type": "object"
},
"platform": {
"description": "Platform of the push device.",
"enum": [
"ios",
"android"
],
"type": "string"
},
"push.recipient": {
"$ref": "#/components/schemas/Recipient"
},
"push.state": {
"description": "the current state of the push device.",
"enum": [
"Active",
"Failing",
"Failed"
],
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"Error": {
"description": "Returned error from failed REST.",
"properties": {
"code": {
"description": "Error code.",
"type": "integer"
},
"href": {
"description": "Link to help with error.",
"type": "string"
},
"message": {
"description": "Message explaining the error's cause.",
"type": "string"
},
"serverId": {
"description": "Server ID with which error was encountered.",
"type": "string"
},
"statusCode": {
"description": "Status error code.",
"type": "integer"
}
},
"type": "object"
},
"Extras": {
"description": "Extras object. Currently only allows for [push](https://www.ably.io/documentation/general/push/publish#channel-broadcast-example) extra.",
"properties": {
"push": {
"$ref": "#/components/schemas/Push"
}
},
"type": "object"
},
"Message": {
"description": "Message object.",
"properties": {
"clientId": {
"description": "The [client ID](https://www.ably.io/documentation/core-features/authentication#identified-clients) of the publisher of this message.",
"type": "string"
},
"connectionId": {
"description": "The connection ID of the publisher of this message.",
"type": "string"
},
"data": {
"description": "The string encoded payload, with the encoding specified below.",
"type": "string"
},
"encoding": {
"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.",
"type": "string"
},
"extras": {
"$ref": "#/components/schemas/Extras"
},
"id": {
"description": "A Unique ID that can be specified by the publisher for [idempotent publishing](https://www.ably.io/documentation/rest/messages#idempotent).",
"readOnly": true,
"type": "string"
},
"name": {
"description": "The event name, if provided.",
"type": "string"
},
"timestamp": {
"description": "Timestamp when the message was received by the Ably, as milliseconds since the epoch.",
"format": "int64",
"readOnly": true,
"type": "integer"
}
},
"type": "object"
},
"Notification": {
"properties": {
"body": {
"description": "Text below title on the expanded notification.",
"type": "string"
},
"collapseKey": {
"description": "Platform-specific, used to group notifications together.",
"type": "string"
},
"icon": {
"description": "Platform-specific icon for the notification.",
"type": "string"
},
"sound": {
"description": "Platform-specific sound for the notification.",
"type": "string"
},
"title": {
"description": "Title to display at the notification.",
"type": "string"
}
},
"type": "object"
},
"Occupancy": {
"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.",
"properties": {
"presenceConnections": {
"description": "The number of connections that are authorised to enter members into the presence channel.",
"type": "integer"
},
"presenceMembers": {
"description": "The number of members currently entered into the presence channel.",
"type": "integer"
},
"presenceSubscribers": {
"description": "The number of connections that are authorised to subscribe to presence messages.",
"type": "integer"
},
"publishers": {
"description": "The number of connections attached to the channel that are authorised to publish.",
"type": "integer"
},
"subscribers": {
"description": "The number of connections attached that are authorised to subscribe to messages.",
"type": "integer"
}
},
"type": "object"
},
"PresenceMessage": {
"properties": {
"action": {
"description": "The event signified by a PresenceMessage.",
"enum": [
"ABSENT",
"PRESENT",
"ENTER",
"LEAVE",
"UPDATE"
],
"readOnly": true,
"type": "string"
},
"clientId": {
"description": "The client ID of the publisher of this presence update.",
"type": "string"
},
"connectionId": {
"description": "The connection ID of the publisher of this presence update.",
"type": "string"
},
"data": {
"description": "The presence update payload, if provided.",
"type": "string"
},
"encoding": {
"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.",
"type": "string"
},
"extras": {
"$ref": "#/components/schemas/Extras"
},
"id": {
"description": "Unique ID assigned by Ably to this presence update.",
"readOnly": true,
"type": "string"
},
"timestamp": {
"description": "Timestamp when the presence update was received by Ably, as milliseconds since the epoch.",
"format": "int64",
"readOnly": true,
"type": "integer"
}
},
"type": "object"
},
"Push": {
"properties": {
"apns": {
"description": "Extends and overrides generic values when delivering via APNs. [See examples](https://www.ably.io/documentation/general/push/publish#payload-structure)",
"properties": {
"notification": {
"$ref": "#/components/schemas/Notification"
}
},
"type": "object"
},
"data": {
"description": "Arbitrary [key-value string-to-string payload](https://www.ably.io/documentation/general/push/publish#channel-broadcast-example).",
"type": "string"
},
"fcm": {
"description": "Extends and overrides generic values when delivering via GCM/FCM. [See examples](https://www.ably.io/documentation/general/push/publish#payload-structure)",
"properties": {
"notification": {
"$ref": "#/components/schemas/Notification"
}
},
"type": "object"
},
"notification": {
"$ref": "#/components/schemas/Notification"
},
"web": {
"description": "Extends and overrides generic values when delivering via web. [See examples](https://www.ably.io/documentation/general/push/publish#payload-structure)",
"properties": {
"notification": {
"$ref": "#/components/schemas/Notification"
}
},
"type": "object"
}
},
"type": "object"
},
"Recipient": {
"description": "Push recipient details for a device.",
"properties": {
"clientId": {
"description": "Client ID of recipient",
"type": "string",
"writeOnly": true
},
"deviceId": {
"description": "Client ID of recipient",
"type": "string",
"writeOnly": true
},
"deviceToken": {
"description": "when using APNs, specifies the required device token.",
"type": "string"
},
"registrationToken": {
"description": "when using GCM or FCM, specifies the required registration token.",
"type": "string"
},
"transportType": {
"description": "Defines which push platform is being used.",
"enum": [
"apns",
"fcm",
"gcm"
],
"type": "string"
}
},
"type": "object"
},
"SignedTokenRequest": {
"allOf": [
{
"$ref": "#/components/schemas/TokenRequest"
},
{
"properties": {
"mac": {
"description": "A signature, generated as an HMAC of each of the above components, using the key secret value.",
"type": "string"
}
},
"required": [
"mac"
],
"type": "object"
}
]
},
"TokenDetails": {
"properties": {
"capability": {
"description": "Regular expression representation of the capabilities of the token.",
"type": "string"
},
"expires": {
"description": "Timestamp of token expiration.",
"type": "integer"
},
"issued": {
"description": "Timestamp of token creation.",
"type": "integer"
},
"keyName": {
"description": "Name of the key used to create the token",
"type": "string"
},
"token": {
"description": "The Ably Token.",
"type": "string"
}
},
"type": "object"
},
"TokenRequest": {
"properties": {
"capability": {
"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.",
"example": {
"channel1": [
"publish",
"subscribe"
]
},
"type": "object"
},
"clientId": {
"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.",
"type": "string"
},
"keyName": {
"description": "Name of the key used for the TokenRequest. The keyName comprises of the app ID and key ID on an API Key.",
"example": "xVLyHw.LMJZxw",
"type": "string"
},
"nonce": {
"description": "An unquoted, un-escaped random string of at least 16 characters. Used to ensure the Ably TokenRequest cannot be reused.",
"type": "string"
},
"timestamp": {
"description": "Time of creation of the Ably TokenRequest.",
"type": "integer"
}
},
"required": [
"keyName",
"capability",
"timestamp",
"nonce"
],
"type": "object"
}
},
"securitySchemes": {
"basicAuth": {
"description": "Basic Authentication using an [API key](https://www.ably.io/documentation/core-features/authentication#basic-authentication).",
"scheme": "basic",
"type": "http"
},
"bearerAuth": {
"description": "Token Authentication using an [Ably Token](https://www.ably.io/documentation/core-features/authentication#basic-authentication), or optionally an [Ably JWT](https://www.ably.io/documentation/core-features/authentication#ably-jwt-process).",
"scheme": "bearer",
"type": "http"
}
}
}
}