ably.com Open in urlscan Pro
2606:4700:10::6814:58c3 Public Scan

Back to summary

Submitted URL:
https://ably.com/documentation/rest-api
Effective URL:
https://ably.com/docs/api/rest-api
Submission: On December 04 via api (December 4th 2023, 3:02:44 am UTC) from BY — Scanned from DE

Form analysis
0 forms found in the DOM

Text Content

^
K
SDKs
API References
Resources
Contact usLogin
Sign up free

API References
1. Overview
2. Realtime SDK
1. Constructor
2. Connection
3. Channels
4. Channel Metadata
5. Messages
6. Presence
7. Authentication
8. History
9. Push Notifications - Admin
10. Push Notifications - Devices
11. Encryption
12. Statistics
13. Types

3. REST SDK
1. Constructor
2. Channels
3. Channel Status
4. Messages
5. Presence
6. Authentication
7. History
8. Push Notifications - Admin
9. Encryption
10. Statistics
11. Types

4. REST API
5. SSE API
6. Control API

REST API REFERENCE

Welcome to the Ably REST API Reference documentation.

The Ably REST API provides a way for a wide range of server and client devices
to communicate with the Ably service over REST. The REST API does not provide a
realtime long-lived connection to Ably, but in all other respects is a simple
subset of the full realtime messaging API.

The primary use-case for the REST API is for servers that are part of the
back-end of an application such as a web application, that publish messages,
issue access tokens (temporary and client-specific) for its various clients,
obtain message and presence history, and retrieve statistics.

The functional scope of the REST API includes:

* Authentication of the server with Ably, and creation of tokens for use by
clients.
* Publication of messages
* Retrieval of message history
* Retrieval of presence state and presence
* Retrieval of statistics for application usage

Using the REST API directly is fully supported, Ably recommends that customers
should use the Ably REST client libraries SDKs, that support a range of
platforms, including the following examples:

* JavaScript
* iOS
* Android
* Java
* Python
* Ruby
* .NET
* Go

The Ably client libraries SDKs are documented, and provide additional features
that improve performance and resilience that the REST API cannot deliver on its
own, such as automatic re-routing around network problems by using alternative
datacenters.

You can also use the Rest#request() method to make arbitrary API calls against
Ably, to use endpoints that libraries do not yet have built-in support for.

COMMON API BEHAVIOR

Copied!

GENERAL

Copied!

The REST API defaults to returning results, and expects request bodies, in JSON
format. An Accept header is used to specify a specific response format – JSON or
an alternative – and the following formats are allowed:

* application/json: JSON;
* application/javascript: for JSONP. A callback query parameter is also
expected, which defaults simply to “callback”;
* application/x-msgpack: for MessagePack, the efficient binary serialization
format that is similar to JSON, but faster and smaller;
* text/html: HTML

It is also possible to specify the response format with the format query
parameter (with supported values being json, jsonp, msgpack, html). Any Accept
header takes precedence over a format parameter.

Similarly, POST requests may contain a request body in JSON or other formats as
indicated by a Content-Type header. The supported content types are:

* application/json: JSON;
* application/x-msgpack: MessagePack, the efficient binary serialization format
that is similar to JSON, but faster and smaller;
* application/x-www-form-urlencoded: Form-encoded.

Specific request and response data types are documented in the context of each
API or route.

A response status code of 20X (200, 201 or 204) indicates success. A successful
result will typically provide a response body but certain operations (such as
DELETE) may respond with a 204 response and no response body.

All other standard HTTP statusCodes signify an error. Errors from all APIs are
returned as an object of the form:

{
error: {
code: <ably error code>,
message: <string>,
statusCode: <http status code>
}
}
Copy
Copied!

Additionally, when you may not have access to the response body due to
limitations of your HTTP client, we include the following custom Ably headers to
work around that problem:

X-Ably-ErrorCode: <ably error code, equivalent to error.code>

Copy
Copied!
X-Ably-ErrorMessage: <string, equivalent to error.message>
Copy
Copied!

The properties of an Ably error are:

code A specific reason code as defined in the public errors definition, where
one is known statusCode Where a code is not available, the statusCode provides a
generic indication of the nature of the failure and maps to standard HTTP
statusCodes message The message string is an English language string that aims
to provide useful information to the developer. It is not necessarily intended
to be an informative string for the end user

Wherever possible, success response bodies contain links, in HATEOS style, to
other resources relevant to the response; where these are present these are
included as href attributes on the applicable part of the response object.

GET, PUT, POST and DELETE are available in all contexts where they make sense.
GET is always idempotent.

VERSIONING

Copied!

By default, all requests receive the latest version of the API, which is
currently 1.1.

When we make backwards-incompatible API changes to the API, we release new
versions. Therefore, we encourage you to explicitly request the version you are
interfacing with in all requests using one of the following mechanisms:

1. Include the X-Ably-Version header. Example:

curl https://rest.ably.io/time \
-H "X-Ably-Version: 1.2"
Copy
Copied!

1. Include the version query string param v. Example:

curl https://rest.ably.io/time?v=1.2
Copy
Copied!

PAGINATION

Copied!

REST APIs whose responses may have unbounded size have paginated responses; that
is, if a full response to the query could exceed a limit (a default or a limit
given as a parameter to the call) the first response contains a subset of the
results, and further “pages” of the result are available on subsequent requests.
Each response (the initial response and responses to each subsequent request) is
accompanied by one or more relative links relating to the current query.

Responses contain one or more of the following relative links:

first a link to the first page of results for this query. This link also makes
the query repeatable; any params that are resolved at query time (for example
default values for omitted time-related params) have their resolved values
included explicitly in the first link. current a stable link to the current page
of results. next on each page except the last in a paginated result, the next
link is a link to the next page of results.

Relative links are presented by default as an RFC 5988 Link HTTP response
header; there is a separate Link header for each relative link accompanying the
response. The rel types used are first, next and current as specified in the
RFC.

A Link header has the format:

Link: <{url}>; rel="{rel}"

where {url} is the URL of the link and {rel} is the relation type.

For example:

Link: <./stats?start=1380794880000&end=1380794881058&limit=100&unit=minute&direction=forwards
&format=json&first_start=1380794880000>; rel="first"

In principle the link URL might be any valid URL but in practice it will always
be a relative URL, and it must be interpreted relative to the original query
URL. Clients should treat link URLs opaquely; in particular, params (such as
first_start in the example above) may be undocumented and unsupported except
where a client uses the link URL in its entirety.

Clients that are unable to process response headers may also request an envelope
response type.

CONTROL OF RESPONSE CONTENT

Copied!

By default the response body of a query response will contain the requested
resource, encoded in the requested format. However, there are also query params
that allow the response body to be adjusted to contain only a subset of the
representation, or a restructured representation.

The following params are supported:

FIELDS

Copied!

Specifying ?fields=<field spec>[,<field spec>, ...] returns the representation
containing only the specified fields. A field spec is a specifier which is
either a single field – in which case the representation contains only that
fields’s value – or a dot-separated sequence of fields, in which case the
representation contains only the fields matching those given in the field spec
at each level in the hierarchy.

EXAMPLE

curl https://rest.ably.io/stats?fields=channels.peak,intervalId \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"

# Response
[{
"channels": { "peak": 2 },
"intervalId": "2015-11-20:15"
}]

API Key:
Demo Only
Copy
Copied!

FLATTEN

Copied!

Specifying ?flatten=true will result in a flattened representation, with the
returned object structure being flattened into one with a single level of long
keys instead of a deep structure. When the results contain array elements, the
array index of each element is included as the corresponding component of the
result key.

EXAMPLE

curl https://rest.ably.io/stats?flatten=true&fields=channels.peak,intervalId \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"

# Response
{
"0.channels.peak": 2,
"0.intervalId": "2015-11-20:15"
}

API Key:
Demo Only
Copy
Copied!

SELECT

Copied!

Specifying ?select=<path spec> returns a representation of the resource
containing only the fields that match the given path specification. Like the
fields param this permits only specific fields to be obtained, but the path spec
may contain wildcard elements, and all matching fields in the representation are
returned.

The result is a partially-flattened representation, as a map whose keys are the
long keys that match the path spec, and the values are the corresponding values.
When the results contain array elements, the array index of each element is
included as the corresponding component of the result key.

EXAMPLE

curl https://rest.ably.io/stats?select=*.channels.* \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"

# Response
[{
"0.channels.peak": 5,
"0.channels.min": 1,
"0.channels.mean": 3,
"0.channels.opened": 2
}]

API Key:
Demo Only
Copy
Copied!

ENVELOPE RESPONSE FORMAT

Copied!

A client that is unable to access response headers or status code can request an
envelope response that contains the usual response, plus Link header information
and the response status code wrapped in an object as a single response body.
This is useful for JSONP and may be useful in other environments. Envelope
responses are only supported for JSON, JSONP and HTML formats.

A client requests an envelope response by including an envelope=<format> param
in the request.

A JSON envelope response body response for a request with an envelope=json param
has the format:

{
"statusCode": <status code>,
"response": <result of API call>,
"rel": {
"first": <URL>,
...
}
}

Copy
Copied!

where the response member references the API result in the usual format. The rel
member, present only in paginated responses, includes each of the rel links
associated with the response.

Envelope responses always are always made with a 200 status code; the status of
the API request itself must be obtained from the statusCode member of the
response body.

AUTHENTICATION

Copied!

To understand the REST API it is easiest first to understand the various
authentication methods that Ably supports. For a detailed explanation, view the
Authentication documentation.

Clients can access Ably, whether using REST or the Realtime service, by two
methods:

1. Basic authentication
2. Token authentication

Each of these is explained in more detail in the following sections.

BASIC AUTHENTICATION

Copied!

Using one of the application keys created via the application dashboard, basic
authentication provides the simplest method to authenticate with Ably, but has
two important limitations:

* the application key is transmitted over the network as part of a request;
therefore it may only be used over TLS (HTTPS or “SSL“) connections. This can
be a performance disadvantage in some network environments where long
round-trip times are amplified by the SSL handshake.
* the client using the API must be in possession of the application key, which
potentially exposes the key to compromise. For example, it is not advisable
to simply embed the key in a script in a public web page.

USAGE IN HTTP REQUEST HEADER

Copied!
Authorization: Basic <Base64-encoded key>

where <Base64-encoded key> is the full application key string obtained through
the dashboard, encoded with RFC 4648 Base64.

Example request:

curl https://rest.ably.io/channels/rest-example/messages \
--header "Authorization: Basic {{API_KEY_BASE64}}"
Copy
Copied!

When using a generic HTTP client library that accepts separate username and
password arguments for an HTTP request, the application key can be split at the
first colon, with the initial segment being used as the username, and the
remaining string (without the leading colon) used as the password.

Example request:

curl https://rest.ably.io/channels/rest-example/messages \
--user "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

TOKEN AUTHENTICATION

Copied!

Token Authentication uses an Ably-compatible token to authenticate with Ably
without sharing a private API key. This can be an Ably Token obtained via the
REST API requestToken endpoint, an Ably JWT signed by your API key, or an
External JWT object with an embedded Ably-compatible token. Tokens are
authentication credentials that are short-lived, and therefore they may more
readily be distributed to clients where there is a risk of compromise. Tokens
may also be issued with a particular scope – such as a limited set of access
rights or capabilities or being limited to use by a specific clientId identity –
and therefore token-based authentication provides the flexibility to implement
access and identity control policies in the application. See the Token
Authentication documentation for more details.

The construction of an Ably TokenRequest is described in the Authentication Ably
TokenRequest spec documentation. The resulting token response object contains
the token properties as defined in Ably TokenRequest spec.

USAGE IN HTTP REQUEST HEADER

Copied!
Authorization: Bearer <Base64-encoded token string>

The <Base64-encoded token string> is either the token attribute of the Ably
Token generated by requestToken encoded with RFC 4648 Base64, or an Ably JWT. If
using a generic HTTP client library it will probably be necessary to add the
Authorization header explicitly.

Example request:

curl https://rest.ably.io/channels/rest-example/messages \
--header "Authorization: Bearer {{TOKEN_BASE64}}"
Copy
Copied!

CHANNEL ROUTES

Copied!

Routes providing access to the messaging service within a channel scope.

PUBLISH ONE OR MORE MESSAGES ON A CHANNEL

Copied!

POST REST.ABLY.IO/CHANNELS/<CHANNELID>/MESSAGES

Publish a message on a channel. Note that since the REST API is stateless,
publication using this API is outside the context of any specific connection.

The request body contains message details and is an object of the form:

{
data: <optional message payload>,
name: <optional event name>,
encoding: <optional encoding>,
clientId: <optional explicit client identifier>,
connectionKey: <optional private connection key>,
id: <optional message ID, see below>,
extras: <optional, see below>
}
Copy
Copied!

In JSON format, the accepted types for the data payload are:

* string
* any JSON-encodable Array or Object.

MessagePack additionally supports byte arrays

A message may be published over REST on behalf of an existing realtime
connection when a valid connectionKey is present. For example, if you want to
publish a message using the REST API so that it appears to come from an existing
connected realtime client, then the connection’s private (secret) connection key
must be included.

Example request:

curl -X POST https://rest.ably.io/channels/rest-example/messages \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM" \
-H "Content-Type: application/json" \
--data '{ "name": "publish", "data": "example" }'
API Key:
Demo Only
Copy
Copied!

If you’re wanting to publish a message idempotently (multiple publishes of the
same message are not duplicated), you should set the id to be unique between
each message. Only the first message received by Ably with a specific id will
then be sent to a channel and its subscribers.

If you wish to publish a message to multiple channels at once, you should
consider using our batch publish functionality.

IDEMPOTENT PUBLISHING

Copied!

It is possible for a client publishing through REST to not receive an
acknowledgement of receipt from Ably for numerous reasons such as network
failures outside of our control. In this scenario, you will likely wish to
re-publish the message, but not risk duplicating it within the network. This is
possible through the addition of an id in the body of your POST, where the id
should uniquely identify the message.

MESSAGE EXTRAS

Copied!

Messages can include an optional extras field, used by extensions to Ably’s core
realtime service.

SEND PUSH NOTIFICATION

Copied!

You can send a push notification to devices subscribed to a channel by setting
the push field in the extras object, like this:

{
<... message fields ...>
extras: {
push: {
data: <arbitrary key-value string-to-string payload>,
notification: {
title: <string, title to display at the notification>,
body: <string, text below title on the expanded notification>,
icon: <string, platform-specific>,
sound: <string, platform-specific>,
collapseKey: <string, platform-specific, used to group notifications together>
}
apns: <optional, extends and overrides generic values when delivering via APNs>,
fcm: <optional, extends and overrides generic values when delivering via FCM>,
}
}
}
Copy
Copied!

For each underlying transport service (like APNs, FCM, etc.) an object can be
provided with the same shape as the parent object, plus any transport-specific
field you may want to add (e. g. content-available for APNs).

Full example of a request publishing a message with a push payload:

curl -X POST https://rest.ably.io/channels/push-enabled:rest-example/messages \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM" \
-H "Content-Type: application/json" \
--data \
'
{
"name": "some event name for realtime receivers",
"data": "example non-push data for realtime receivers",
"extras": {
"push": {
"notification": {
"title": "Hello from Ably!",
"body": "Example push notification from Ably."
},
"data": {
"foo": "bar",
"baz": "qux"
},
"apns": {
"notification": {
"content-available": 1,
"sound": "ably-ios.wav"
}
}
}
}
}
'
API Key:
Demo Only
Copy
Copied!

PARAMETERS

enveloped if present and equal to false, does an unenveloped publish

OPTIONS

Content-Type application/json, application/x-msgpack or
application/x-www-form-urlencoded Accept application/json (the default),
application/x-msgpack Auth required yes (basic or token)

RETURNS

When successful, returns status code 201 and an object with channel and
messageId properties, in case you want to know the message ID assigned to
correlate with messages received by realtime subscribers or Ably Integration
recipients. When unsuccessful, returns an error as an ErrorInfo object.

UNENVELOPED PUBLISH

Copied!

If the enveloped parameter is present and set to false, the request body is
interpreted as the data payload for a message to be published, rather than (as
it would normally be) as a Message object or array of Message objects. This can
be useful if, for example, you want an Ably publish to be triggered by a webhook
from some third-party service where you cannot control the format of the request
body.

Example json request:

curl -X POST https://rest.ably.io/channels/rest-example/messages?enveloped=false \
-H 'content-type: application/json' --data '{"some":"json"}' \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

Example plain text request:

curl -X POST https://rest.ably.io/channels/rest-example/messages?enveloped=false \
-H 'content-type: text/plain' --data 'some plain text' \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

HEADERS AND PARAMETERS

X-Ably-MessageId Optional message ID, used for idempotent publishing. Can also
be specified as a messageId querystring parameter. Equivalent to Message.id
X-Ably-Name Optional message name. Can also be specified as a name querystring
parameter. Equivalent to Message.name X-Ably-ConnectionKey Optional connection
key, used to publish on behalf of a realtime connection, see documentation
above. Can also be specified as a connectionKey querystring parameter.
Equivalent to Message.connectionKey X-Ably-Encoding Optional message encoding.
Allows you to specify the encoding of the message to allow recipient client
libraries to decode it. For example, an encoding of json will instruct client
libraries to automatically JSON-parse the message on receipt. Also useful if
sending an encrypted message, to allow client libraries to decrypt it (assuming
they have the correct key). Must be in the correct format per our client lib
development guide ; if unsure, leave this unspecified. Can also be specified as
an encoding querystring parameter. Equivalent to Message.encoding
X-Ably-ClientId Optional client ID, base64-encoded (to allow arbitrary unicode).
Can also be specified as a clientId querystring parameter (not base64-encoded).
Equivalent to Message.clientId

OPTIONS

Content-Type text/plain (for utf-8 text request bodies) or
application/octet-stream (for binary request bodies). application/json will also
work, and is equivalent to specifying a content-type of text/plain together with
X-Ably-Encoding of json. Accept application/json (the default),
application/x-msgpack Auth required yes (basic or token)

RETURNS

When successful, returns an object with channel and messageId properties, in
case you want to know the message ID assigned to correlate with messages
received by realtime subscribers or integrations recipients. When unsuccessful,
returns an error as an ErrorInfo object.

RETRIEVE MESSAGE HISTORY FOR A CHANNEL

Copied!

GET REST.ABLY.IO/CHANNELS/<CHANNELID>/MESSAGES

If a channel is configured to persist messages, then all messages on that
channel, within your account retention period, are available via this API
endpoint. If persistence is not configured, then there are no guarantees as to
how many historical messages will be available for the channel. Find out more
about message persistence.

Example request:

curl https://rest.ably.io/channels/rest-example/messages \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

PARAMETERS

start beginning of time The start of the query interval as a time in
milliseconds since the epoch. A message qualifies as a member of the result set
if it was received at or after this time. end now The end of the query interval
as a time in milliseconds since the epoch. A message qualifies as a member of
the result set if it was received at or before this time. limit 100 The maximum
number of records to return. A limit greater than 1,000 is invalid. direction
backwards The direction of this query. The direction determines the order of the
returned result array, but also determines which end of the query interval is
the start point for the search. For example, a forwards query uses start as the
start point, whereas a backwards query uses end as the start point.

OPTIONS

Content-Type not applicable Accept application/json by default, or
application/x-msgpack, text/html Auth required yes (basic or token)

RETURNS

In each case a successful result is a paginated response with an array
containing the items that match the query (and it may be empty).

[{
id: <unique message id>
name: <event name>,
data: <message payload>,
timestamp: <message timestamp in ms since epoch>
}]
Copy
Copied!

RETRIEVE INSTANTANEOUS PRESENCE STATUS FOR A CHANNEL

Copied!

GET REST.ABLY.IO/CHANNELS/<CHANNELID>/PRESENCE

Obtain the set of members currently present for a channel.

Example request:

curl https://rest.ably.io/channels/rest-example/presence \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

PARAMETERS

clientId optional filter to restrict members present with that clientId
connectionId optional filter to restrict members present with that connectionId
limit 100 The maximum number of records to return. A limit greater than 1,000 is
invalid.

OPTIONS

Content-Type not applicable Accept application/json by default, or
application/x-msgpack, text/html Auth required yes (basic or token)

RETURNS

A successful request returns a paginated response with an array containing the
members that are currently present on the given channel. If there are no members
present, an empty collection is returned.

[{
id: <a unique member identifier generated by Ably>,
clientId: <member client id provided by the client>,
connectionId: <a unique connection id generated by Ably>
timestamp: <message timestamp in ms since epoch>
action: <presence state>,
data: <optional clientData provided by the client>
}]
Copy
Copied!

RETRIEVE PRESENCE STATE HISTORY FOR A CHANNEL

Copied!

GET REST.ABLY.IO/CHANNELS/<CHANNELID>/PRESENCE/HISTORY

Obtain the history of presence messages for a channel.

Example request:

curl https://rest.ably.io/channels/rest-example/presence/history \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

PARAMETERS

OPTIONS

Content-Type not applicable Accept application/json by default, or
application/x-msgpack, text/html Auth required yes (basic or token)

RETURNS

RETRIEVE METADATA FOR A CHANNEL

Copied!

This returns a ChannelDetails for the given channel, indicating global
occupancy. A side-effect of this request, in the current version of this API, is
that it will cause the channel in question to become activated; therefore it is
primarily intended to be used in conjunction with the enumeration API or in
situations where the application has another means to know whether or not a
given channel is active.

Example request:

curl https://rest.ably.io/channels/<channelId> \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

The credentials presented with the request must include the channel-metadata
permission for the channel in question.

Client libraries currently do not support this API, but it is usable via the
generic request API.

ENUMERATE ALL ACTIVE CHANNELS

Copied!

This enumerates all active channels in the application. This is a paginated API
following the same API conventions as other paginated APIs in the REST
interface.

This API is intended for occasional use by your servers only; for example, to
get an initial set of active channels to be kept up to date using the channel
lifecycle metachannel. It is heavily rate-limited: only a single in-flight
channel enumeration call is permitted to execute at any one time. Further
concurrent calls will be refused with an error with code 42912.

Example request:

curl https://rest.ably.io/channels \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

This will return either a list of channel names, or a ChannelDetails object
depending on what options you’ve specified.

The following parameters are supported:

limit 100 optionally specifies the maximum number of results to return. A limit
greater than 1000 is unsupportedType: integer prefix optionally limits the query
to only those channels whose name starts with the given prefixType: string by
value optionally specifies whether to return just channel names (by=id) or
ChannelDetails (by=value is the default, but if you do not actually need the
extra information you get with that, we strongly recommend you use by=id, which
will be faster)

The credentials presented with the request must include the channel-metadata
permission for the wildcard resource '*'.

Client libraries do not provide a dedicated API to enumerate channels, but make
this available using the request method. When using this, you can simply iterate
through the PaginatedResults to enumerate through the results.

Enumeration is possible of all channels in an app, by repeated calls to the API,
following the next relative link on each successive call, until there is no next
relative link. However, this is subject to several limitations:

* Channels that become active, or become inactive, between the first and last
request in the sequence, might or might not appear in the result. The API
guarantees that if a channel is continuously active from the time that the
first request is made until the time that the last request completes, then it
is guaranteed to be present in the result. Similarly, if a channel is
continuously inactive between those times then it is guaranteed not to be
present in the result;
* Since the state of the cluster may change between successive calls, a
pagination sequence may become invalid, in which case the request will
respond with an error with code 40011. In this case, to get a complete
result, it is necessary to start the enumeration again from the beginning.
Other API options to deal with this possibility maybe provided in later
versions of this API. Enumerations that are satisfiable in the first response
page do not have this issue.
* The API does not guarantee that the limit will be achieved even if that would
be possible. For example, if you specify a limit of 100, the API may return
only 37 results together with a next link to get the next page, even if you
have more than 37 channels. In the extreme case, the API may return 0 results
with a next link. In particular this may be the case if you have a large
number of active channels but are specifying a prefix that excludes a
significant proportion of them.
* The API does not guarantee that there will be no duplicated results between
different pages, especially if a channel is alive in multiple regions. (It
does not currently do so, but it may begin to do so with no warning or
deprecation period, so your implementation should be able to cope with
duplication)

PUSH

Copied!

POST REST.ABLY.IO/PUSH/DEVICEREGISTRATIONS

The request body contains device and push recipient details, and is an object of
the form:

{
id: <string>,
clientId: <optional, string, client identifier to associate with registration>,
platform: <string, one of ios, android or browser>,
formFactor: <string, one of phone, tablet, desktop, tv, watch, car or embedded>,
metadata: <optional, object, with flexible key/value string pairs>,
push: {
recipient: {
transportType: <string, one of fcm or apns>,
<additional key/value string pairs for transport-specific recipient address>
}
}
}
Copy
Copied!

The recipient address attributes are necessary and vary by underlying transport
service.

For APNs:

{
deviceToken: <string>
}
Copy
Copied!

For FCM:

{
registrationToken: <string>
}
Copy
Copied!

Example request:

curl -X POST https://rest.ably.io/push/deviceRegistrations \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
-H "Content-Type: application/json" \
--data \
'{
"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"platform": "ios",
"formFactor": "phone",
"push": {
"recipient": {
"transportType": "apns",
"deviceToken": "740f4707bebcf74f9b7c25d48e3358945f6aa01da5ddb387462c7eaf61bb78ad"
}
}
}'
API Key:
Demo Only
Copy
Copied!

PARAMETERS

None

OPTIONS

Content-Type application/json, application/x-msgpack or
application/x-www-form-urlencoded Accept application/json by default, or
application/x-msgpack, text/html Auth required yes (basic or token with
push-subscribe or push-admin capability; when registering for a client ID with a
push-subscribe capability, the token must be associated with that client ID)

A successful request returns the just-registered device details. It includes an
updateToken, which is a token that can be used by typically a mobile device to
authenticate with Ably later and update an existing device registration (for
example, for updating a FCM registration token).

An unsuccessful request returns an error.

UPDATE A DEVICE REGISTRATION

Copied!

Device registrations can be either upserted (the existing registration is
replaced entirely) with a PUT operation, or specific attributes of an existing
registration can be updated using a PATCH operation:

PUT REST.ABLY.IO/PUSH/DEVICEREGISTRATIONS/<DEVICEID>

Copied!

The body must have the same shape as when registering the device. The PUT
operation will replace the existing device registration, however please bear in
mind that a registered device in Ably is largely immutable. As such, only the
following attributes are currently updatable and any attempt to modify other
fields will result in the update failing:

* clientId
* metadata
* push.recipient

Additionally, if the push.state or updateToken attributes are provided, they
will be accepted if they match the existing value. However if they differ (and
are not null or omitted), then the update will fail.

If you need to make changes to any other fields, you will have to deregister the
existing device and then register a new one.

Example request:

curl -X PUT https://rest.ably.io/push/deviceRegistrations/01ARZ3NDEKTSV4RRFFQ69G5FAV \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
-H "Content-Type: application/json" \
--data \
'{
"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"platform": "ios",
"formFactor": "phone",
"metadata": {
"timezone": "PST"
},
"push": {
"recipient": {
"transportType": "apns",
"deviceToken": "740f4707bebcf74f9b7c25d48e3358945f6aa01da5ddb387462c7eaf61bb78ad"
}
}
}'
API Key:
Demo Only
Copy
Copied!

PARAMETERS

None

OPTIONS

A successful request returns the updated device details.

An unsuccessful request returns an error.

PATCH REST.ABLY.IO/PUSH/DEVICEREGISTRATIONS/<DEVICEID>

Copied!

The body must have the same shape as when registering the device, except only
fields to be changed should be provided. Any fields provided replace existing
values. Please bear in mind that fields whose values are structured (JSON-like
arrays or objects) types will replace existing values as opposed to be merged
into existing values. metadata and push.recipient are examples of these types.
Currently only the following attributes are currently updatable and any attempt
to modify other fields will result in the update failing:

* clientId (this field is only editable with a push-admin capability)
* metadata (this field is only editable with a push-admin capability)
* push.recipient

If you need to make changes to any other fields, you will have to deregister the
existing device and then register a new one.

Example request:

curl -X PATCH https://rest.ably.io/push/deviceRegistrations/01ARZ3NDEKTSV4RRFFQ69G5FAV \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
-H "Content-Type: application/json" \
--data \
'{
"metadata": {
"myKey": "value"
}
}'
API Key:
Demo Only
Copy
Copied!

PARAMETERS

None

OPTIONS

Content-Type application/json, application/x-msgpack or
application/x-www-form-urlencoded Accept application/json by default, or
application/x-msgpack, text/html Auth required yes (basic or token with
push-admin capability, or token authentication using the device’s update token)

A successful request returns the updated device details.

An unsuccessful request returns an error.

GET DETAILS FROM A REGISTERED DEVICE

Copied!

GET REST.ABLY.IO/PUSH/DEVICEREGISTRATIONS/<DEVICEID>

Obtain the details for a device registered for receiving push registrations.

Example request:

curl https://rest.ably.io/push/deviceRegistrations/01ARZ3NDEKTSV4RRFFQ69G5FAV \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

PARAMETERS

None.

OPTIONS

Content-Type not applicable Accept application/json by default, or
application/x-msgpack, text/html Auth required yes (basic or token with
push-admin capability)

RETURNS

A JSON object like:

{
id: <string>,
clientId: <optional, string>
platform: <string>
formFactor: <string>,
metadata: <object>,
updateToken: <string>,
push: {
recipient: {
transportType: <string>,
<additional recipient address key/value pairs>
},
state: <active or failed>,
error: {
code: <string>,
statusCode: <string>,
message: <string>
}
}
}
Copy
Copied!

or a 404 error if a device by that ID does not exist.

If Ably could not register the device on behalf of the push notifications
provider, then push.error contains the relevant error information.

LIST REGISTERED DEVICES

Copied!

GET REST.ABLY.IO/PUSH/DEVICEREGISTRATIONS

Obtain the details for devices registered for receiving push registrations.

Example request:

curl https://rest.ably.io/push/deviceRegistrations \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

PARAMETERS

deviceId optional filter to restrict to devices associated with that deviceId
clientId optional filter to restrict to devices associated with that clientId
limit 100 The maximum number of records to return. A limit greater than 1,000 is
invalid.

OPTIONS

Content-Type not applicable Accept application/json by default, or
application/x-msgpack, text/html Auth required yes (basic or token with
push-admin capability)

RETURNS

A successful request returns a paginated response of:

[{
id: <string>,
clientId: <optional, string>
platform: <string>
formFactor: <string>,
metadata: <object>,
updateToken: <string>,
push: {
recipient: {
transportType: <string>,
<additional recipient address key/value pairs>
},
state: <active or failed>
}
}]
Copy
Copied!

RESET A REGISTERED DEVICE’S UPDATE TOKEN

Copied!

POST REST.ABLY.IO/PUSH/DEVICEREGISTRATIONS/<DEVICEID>/RESETUPDATETOKEN

Example request:

curl -X POST https://rest.ably.io/push/01ARZ3NDEKTSV4RRFFQ69G5FAV/resetUpdateToken \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

PARAMETERS

None

OPTIONS

Accept application/json by default, or application/x-msgpack, text/html Auth
required yes (basic or token with push-admin capability, or token authentication
using the device’s update token)

A successful request returns the updated device details.

A unsuccessful request returns an error.

UNREGISTER A SINGLE DEVICE FOR PUSH NOTIFICATIONS

Copied!

DELETE REST.ABLY.IO/PUSH/DEVICEREGISTRATIONS/<DEVICEID>

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

Please note that this operation is done asynchronously so immediate requests
subsequent to this delete request may briefly still return the device.

Example request:

curl -X DELETE \
https://rest.ably.io/push/deviceRegistrations/01ARZ3NDEKTSV4RRFFQ69G5FAV \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

PARAMETERS

None

OPTIONS

Content-Type not applicable Auth required yes (basic or token with push-admin
capability)

RETURNS

A successful request returns an empty response.

An unsuccessful request returns an error.

UNREGISTER MATCHING DEVICES FOR PUSH NOTIFICATIONS

Copied!

DELETE REST.ABLY.IO/PUSH/DEVICEREGISTRATIONS

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

Please note that this operation is done asynchronously so immediate requests
subsequent to this delete request may briefly still return the device.

Example request:

curl -X DELETE \
https://rest.ably.io/push/deviceRegistrations?deviceId=01ARZ3NDEKTSV4RRFFQ69G5FAV \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

PARAMETERS

deviceId Filter to restrict to subscriptions for that deviceId. Cannot be used
with clientId. clientId Filter to restrict to subscriptions associated with that
clientId. Cannot be used with deviceId.

OPTIONS

Content-Type not applicable Auth required yes (basic or token with push-admin
capability)

RETURNS

A successful request returns an empty response.

An unsuccessful request returns an error.

SUBSCRIBE TO A CHANNEL

Copied!

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

POST REST.ABLY.IO/PUSH/CHANNELSUBSCRIPTIONS

The request body contains subscription details and is an object of the form:

{
channel: <string>,
deviceId: <optional, string, must be set when clientId is empty, cannot be used with clientId>,
clientId: <optional, string, must be set when deviceId is empty, cannot be used with deviceId>
}
Copy
Copied!

curl -X POST https://rest.ably.io/push/channelSubscriptions \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
-H "Content-Type: application/json" \
--data \
'
{
"channel": "rest-example",
"deviceId": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
}
'
API Key:
Demo Only
Copy
Copied!

PARAMETERS

None

OPTIONS

Content-Type application/json, application/x-msgpack or
application/x-www-form-urlencoded Accept application/json by default, or
application/x-msgpack, text/html Auth required yes (basic or token with
push-subscribe or push-admin capability; when subscribing for a client ID with a
push-subscribe capability, the token must be associated with that client ID)

A successful request returns an empty object.

A unsuccessful request returns an error.

UNSUBSCRIBE FROM PUSH NOTIFICATIONS FOR CHANNELS

Copied!

DELETE REST.ABLY.IO/PUSH/CHANNELSUBSCRIPTIONS

Stop receiving push notifications when push messages are published on the
specified channels.

Please note that this operation is done asynchronously so immediate requests
subsequent to this delete request may briefly still return the subscription.

Example request:

curl -X DELETE \
https://rest.ably.io/push/channelSubscriptions?deviceId=01ARZ3NDEKTSV4RRFFQ69G5FAV \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

PARAMETERS

channel string, optional. If not set, all subscriptions on all channels will be
deleted. deviceId Filter to restrict to subscriptions for that deviceId. Cannot
be used with clientId. clientId Filter to restrict to subscriptions associated
with that clientId. Cannot be used with deviceId.

OPTIONS

Content-Type not applicable Auth required yes (basic or token with
push-subscribe or push-admincapability; when deleting by client ID with a
push-subscribe capability, the token must be associated with that client ID)

RETURNS

A successful request returns an empty response.

An unsuccessful request returns an error.

LIST CHANNEL SUBSCRIPTIONS

Copied!

GET REST.ABLY.IO/PUSH/CHANNELSUBSCRIPTIONS

Get a list of push notification subscriptions to channels.

Example request:

curl https://rest.ably.io/push/channelSubscriptions \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

PARAMETERS

channel Filter to restrict to subscriptions associated with that channel.
clientId Filter to restrict to subscriptions associated with that clientId.
Cannot be used with deviceId, unless concatFilters is set to true. deviceId
Filter to restrict to subscriptions for that deviceId. Cannot be used with
clientId, unless concatFilters is set to true. concatFilters false Find all
device registrations which match either clientId or deviceId. Set this to true
in order to set both clientId and deviceId. limit 100 The maximum number of
records to return. A limit greater than 1,000 is invalid.

OPTIONS

Content-Type not applicable Accept application/json by default, or
application/x-msgpack, text/html Auth required yes (basic or token with
push-admin capability)

RETURNS

A successful request returns a paginated response of:

[{
channel: <string>,
clientId: <string, only present when deviceId is not present>
deviceId: <string, only present when clientId is not present>,
}]
Copy
Copied!

LIST ALL CHANNELS WITH AT LEAST ONE SUBSCRIBED DEVICE

Copied!

GET REST.ABLY.IO/PUSH/CHANNELS

Example request:

curl https://rest.ably.io/push/channels \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM"
API Key:
Demo Only
Copy
Copied!

PARAMETERS

None

OPTIONS

Content-Type not applicable Accept application/json by default, or
application/x-msgpack, text/html Auth required yes (basic or token with
push-admin capability)

RETURNS

A successful request returns a paginated response of:

[<string, channel name>]
Copy
Copied!

PUBLISH A PUSH NOTIFICATION TO A SINGLE DEVICE

Copied!

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

If you want to send a push notification to multiple devices or use a more
flexible publish-subscribe architecture so that you don’t need to know about
recipient devices’s details, we recommend you look at registering devices for
push, then subscribe them to channels, and then send messages to the channels
with push payloads.

This direct publish endpoint is designed for customers who typically have legacy
devices they wish to push directly to, or if they want to publish to all devices
for a single user.

POST REST.ABLY.IO/PUSH/PUBLISH

The request body is an object of the form:

{
recipient: <object>
<... rest of the fields just like a normal push-enabled message's extras.push object ...>
}
Copy
Copied!

Example request:

curl -X POST https://rest.ably.io/push/publish \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM" \
-H "Content-Type: application/json" \
--data \
'
{
"recipient": {
"clientId": "myClientId"
},
"notification": {
"title": "Hello from Ably!",
"body": "Example push notification from Ably."
},
"data": {
"foo": "bar",
"baz": "qux"
}
}'
API Key:
Demo Only
Copy
Copied!

The recipient field supports delivering either to devices registered to Ably by
device ID, by their associated client ID, or directly to devices using the
underlying notifications service (FCM, APNs, etc.), thus bypassing registrations
to Ably altogether.

By device ID:

{
deviceId: <string>
}
Copy
Copied!

By client ID:

{
clientId: <string>
}
Copy
Copied!

For APNs devices:

{
transportType: "apns",
deviceToken: <string>
}
Copy
Copied!

For FCM devices:

{
transportType: <fcm>,
registrationToken: <string>
}
Copy
Copied!

The rest of the fields are normal push-enabled Ably message’s push.extras
object.

PARAMETERS

None

OPTIONS

Content-Type application/json, application/x-msgpack or
application/x-www-form-urlencoded Accept not applicable Auth required yes (basic
or token with push-admin capability)

A successful request returns an empty response.

An unsuccessful request returns an error.

AUTHENTICATION

Copied!

REQUEST AN ACCESS TOKEN

Copied!

POST REST.ABLY.IO/KEYS/<KEYNAME>/REQUESTTOKEN

This is the means by which clients obtain access tokens to use the service. The
construction of an Ably TokenRequest is described in the Authentication Ably
TokenRequest spec documentation. The resulting token response object contains
the token properties as defined in Ably TokenRequest spec.

Example request:

curl -X POST "https://rest.ably.io/keys/{{API_KEY_NAME}}/requestToken" \
-u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM" \
-H "Content-Type: application/json" \
--data '{ "keyName": "{{API_KEY_NAME}}", "timestamp": {{MS_SINCE_EPOCH}} }'
API Key:
Demo Only
Copy
Copied!

PARAMETERS

None

OPTIONS

Request body signed or unsigned Ably TokenRequest. All Ably TokenRequests
require values for keyName and timestamp attributes. In addition, signed Ably
TokenRequests require values for attributes nonce and mac. Content-Type
text/plain Accept application/json by default, or application/x-msgpack Auth
required no (for signed Ably TokenRequests), yes (for unsigned Ably
TokenRequests, basic or token permitted)

RETURNS

A successful request will return a token details object containing the token
string.

{
"token": "xVLyHw.CLchevH3hF....MDh9ZC_Q", // token string
"keyName": "xVLyHw.mDYnFA",
"issued": 1428356667,
"expires": 1428360267,
"capability": "{\"*\":[\"*\"]}"
}
Copy
Copied!

REVOKE TOKENS

Copied!

POST REST.ABLY.IO/KEYS/<KEYNAME>/REVOKETOKENS

Provides a mechanism to revoke tokens, where keyName is appId.keyId.

Example request:

curl -u "xVLyHw.zc0c7g:Bjf96wkHyq46mwwVQ6i2H2mWF7F5OygISDSzK64mLGM" -X POST https://rest.ably.io/keys/{{API_KEY_NAME}}/revokeTokens \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{"targets": [ "clientId:client1@example.com" ]}'
API Key:
Demo Only
Copy
Copied!

PARAMETERS

None

OPTIONS

Request body A JSON object containing target specifiers identifying tokens to be
revoked. Content-Type application/json Accept application/json Auth required
yes, basic authentication.

The request body has the following properties:

targets An array of target specifier strings. issuedBefore Optional number (Unix
timestamp in milliseconds); if not specified it is set to the current time. The
token revocation only applies to tokens issued before this timestamp. A request
with an issuedBefore in the future, or more than an hour in the past will be
rejected. allowReauthMargin The allowReauthMargin bool permits a token renewal
cycle to take place without needing established connections to be dropped, by
postponing enforcement to 30 seconds in the future, and sending any existing
connections a hint to obtain (and upgrade the connection to use) a new token. It
defaults to false, meaning that the effect is near-immediate.

RETURNS

A successful request returns status 201. An example response body is as follows:

[
{
"target": "clientId:foo",
"issuedBefore": 1636022994797,
"appliesAt": 1636022994797
},
{
"target": "clientId:bar",
"issuedBefore": 1636022994797,
"appliesAt": 1636022994797
}
]
Copy
Copied!

In the response, appliesAt is the time the revocation will take effect. This is
the current time by default, or about 30s in the future if you specify
allowReauthMargin in the request.

The response is comparable to that of Batch publish. If some tokens can be
revoked, and some can’t, you receive a batch partial response.

ably.com Open in urlscan Pro 2606:4700:10::6814:58c3 Public Scan

Form analysis 0 forms found in the DOM

Text Content

ably.com Open in urlscan Pro
2606:4700:10::6814:58c3 Public Scan

Form analysis
0 forms found in the DOM