Warning: You are viewing an old version (0.8) of this documentation. We recommend you view the latest version 1.2.
API Reference

REST API Specification

Channel routes

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

Publish one or more messages on a channel

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:

{
  name: <event name>,
  data: <message payload>,
  encoding: <optional encoding>,
  clientId: <optional explicit client identifier>,
  connectionKey: <optional private connection key>
}

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. See a publish on behalf of a realtime client example.

Example request:

curl -X POST https://rest.ably.io/channels/rest-example/messages \
 -u "xVLyHw.gw_tWg:Mf8nxaxXklmwyh09kBSt0TfqialrMufOCblGXTEi-5U" \
 -H "Content-Type: application/json" \
 --data '{ "name": "publish", "data": "example" }'
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)
Returns

Nothing when successful, else returns an error.

Retrieve message history for a channel

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.gw_tWg:Mf8nxaxXklmwyh09kBSt0TfqialrMufOCblGXTEi-5U"
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>
}]

Retrieve instantaneous presence status for a channel

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.gw_tWg:Mf8nxaxXklmwyh09kBSt0TfqialrMufOCblGXTEi-5U"
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 identifer 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>
}]

Retrieve presence state history for a channel

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.gw_tWg:Mf8nxaxXklmwyh09kBSt0TfqialrMufOCblGXTEi-5U"
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

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 identifer 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>
}]

Authentication

Request an access token

POST rest.ably.io/keys/<keyName>/requestToken

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

Example request:

curl -X POST "https://rest.ably.io/keys/xVLyHw.gw_tWg/requestToken" \
 -u "xVLyHw.gw_tWg:Mf8nxaxXklmwyh09kBSt0TfqialrMufOCblGXTEi-5U" \
 -H "Content-Type: application/json" \
 --data '{ "keyName": "xVLyHw.gw_tWg", "timestamp": _VAR_MS_SINCE_EPOCH_VAR_ }'
Parameters

None

Options
Request body
signed or unsigned token request. All token requests require values for keyName and timestamp attributes. In addition, signed token 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 token requests), yes (for unsigned token requests, 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": "{\"*\":[\"*\"]}"
}

Application routes

Routes providing access to the messaging service within an application scope.

Retrieve usage statistics for an application

GET rest.ably.io/stats

Example request:

curl https://rest.ably.io/stats?unit=hour \
 -u "xVLyHw.gw_tWg:Mf8nxaxXklmwyh09kBSt0TfqialrMufOCblGXTEi-5U"

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.

Stats queries are made by specifying a query interval and the granularity expected in the results. The query interval is expressed as a start and end time, each being a timestamp in milliseconds since the epoch. Stats are aggregated by the system in ‘sub-minute’ intervals of 6s (ie 0.1m), so query interval start and end times are rounded down to the nearest sub-minute boundary.

Parameters
start
beginning of time The start of the query interval as a time in milliseconds since the epoch.
end
now The end of the query interval as a time in milliseconds since the epoch.
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.
unit
minute One of the values minute, hour, day or month, specifying the unit of aggregation in the returned results.
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).

Stats records contain a hierarchy of elements relating to messages, connections and other resources consumed in an interval. Any single record may contain a subset of the elements, omitting empty sections.

See a complete example of a statistics response.

Utilities

Get the service time

GET rest.ably.io/time

This returns the service time in milliseconds since the epoch. This may be used by clients that do not have local access to a sufficiently accurate time source when generating a token request. (Token requests include a timestamp and have a limited validity period to help defend against replay attacks.)

The result is a JSON-encoded array of length 1 containing the time result as a number.

curl http://rest.ably.io/time
Parameters

None

Options
Content-Type
not applicable
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
no
Returns
[ _VAR_MS_SINCE_EPOCH_VAR_ ]

Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.