@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Platform API
@base https://rest.ably.io
@version 1.1.1
@auth Bearer basic | Bearer bearer
@endpoints 22
@hint download_for_search
@toc channels(6), push(13), keys(1), stats(1), time(1)

@group channels
@endpoint GET /channels/{channel_id}/messages
@desc Get message history for a channel
@required {channel_id: str # The [Channel's ID](https://www.ably.io/documentation/rest/channels).}
@optional {start: str, limit: int=100, end: str=now, direction: str(forwards/backwards)=backwards}
@returns(2XX) OK

@endpoint POST /channels/{channel_id}/messages
@desc Publish a message to a channel
@required {channel_id: str # The [Channel's ID](https://www.ably.io/documentation/rest/channels).}
@optional {name: str # The event name, if provided., data: str # The string encoded payload, with the encoding specified below., id: str # A Unique ID that can be specified by the publisher for [idempotent publishing](https://www.ably.io/documentation/rest/messages#idempotent)., timestamp: int(int64) # Timestamp when the message was received by the Ably, as milliseconds since the epoch., encoding: str # 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., clientId: str # The [client ID](https://www.ably.io/documentation/core-features/authentication#identified-clients) of the publisher of this message., connectionId: str # The connection ID of the publisher of this message., extras: map{push: map} # Extras object. Currently only allows for [push](https://www.ably.io/documentation/general/push/publish#channel-broadcast-example) extra.}
@returns(2XX) {channel: str, messageId: str} # OK

@endpoint GET /channels/{channel_id}/presence
@desc Get presence of a channel
@required {channel_id: str # The [Channel's ID](https://www.ably.io/documentation/rest/channels).}
@optional {clientId: str, connectionId: str, limit: int=100}
@returns(200) OK

@endpoint GET /channels/{channel_id}/presence/history
@desc Get presence history of a channel
@required {channel_id: str # The [Channel's ID](https://www.ably.io/documentation/rest/channels).}
@optional {start: str, limit: int=100, end: str=now, direction: str(forwards/backwards)=backwards}
@returns(2XX) OK

@endpoint GET /channels/{channel_id}
@desc Get metadata of a channel
@required {channel_id: str # The [Channel's ID](https://www.ably.io/documentation/rest/channels).}
@returns(200) {channelId: str, region: str, isGlobalMaster: bool, status: map{isActive: bool, occupancy: map{publishers: int, subscribers: int, presenceSubscribers: int, presenceConnections: int, presenceMembers: int}}} # OK

@endpoint GET /channels
@desc Enumerate all active channels of the application
@optional {limit: int=100, prefix: str # Optionally limits the query to only those channels whose name starts with the given prefix, by: str(value/id) # optionally specifies whether to return just channel names (by=id) or ChannelDetails (by=value)}
@returns(2XX) OK

@endgroup

@group push
@endpoint GET /push/deviceRegistrations
@desc List devices registered for receiving push notifications
@optional {deviceId: str # Optional filter to restrict to devices associated with that deviceId., clientId: str # Optional filter to restrict to devices associated with that clientId., limit: int=100 # The maximum number of records to return.}
@returns(2XX) {id: str, clientId: str, formFactor: str, metadata: map, platform: str, deviceSecret: str, push.recipient: map{transportType: str, deviceToken: str, registrationToken: str, encryptionKey: map, clientId: str, deviceId: str}, push.state: str} # OK

@endpoint POST /push/deviceRegistrations
@desc Register a device for receiving push notifications
@optional {id: str # Unique identifier for the device generated by the device itself., clientId: str # Optional trusted client identifier for the device., formFactor: str(phone/tablet/desktop/tv/watch/car/embedded) # Form factor of the push device., metadata: map # Optional metadata object for this device. The metadata for a device may only be set by clients with push-admin privileges and will be used more extensively in the future with smart notifications., platform: str(ios/android/browser) # Platform of the push device., deviceSecret: str # Secret value for the device., push.recipient: map{transportType: str, deviceToken: str, registrationToken: str, encryptionKey: map, clientId: str, deviceId: str} # Push recipient details for a device., push.state: str(Active/Failing/Failed) # the current state of the push device.}
@returns(2XX) {id: str, clientId: str, formFactor: str, metadata: map, platform: str, deviceSecret: str, push.recipient: map{transportType: str, deviceToken: str, registrationToken: str, encryptionKey: map, clientId: str, deviceId: str}, push.state: str} # OK

@endpoint DELETE /push/deviceRegistrations
@desc Unregister matching devices for push notifications
@optional {deviceId: str # Optional filter to restrict to devices associated with that deviceId. Cannot be used with clientId., clientId: str # Optional filter to restrict to devices associated with that clientId. Cannot be used with deviceId.}
@returns(2XX) OK

@endpoint GET /push/deviceRegistrations/{device_id}
@desc Get a device registration
@required {device_id: str # Device's ID.}
@returns(2XX) {id: str, clientId: str, formFactor: str, metadata: map, platform: str, deviceSecret: str, push.recipient: map{transportType: str, deviceToken: str, registrationToken: str, encryptionKey: map, clientId: str, deviceId: str}, push.state: str} # OK

@endpoint PUT /push/deviceRegistrations/{device_id}
@desc Update a device registration
@required {device_id: str # Device's ID.}
@optional {id: str # Unique identifier for the device generated by the device itself., clientId: str # Optional trusted client identifier for the device., formFactor: str(phone/tablet/desktop/tv/watch/car/embedded) # Form factor of the push device., metadata: map # Optional metadata object for this device. The metadata for a device may only be set by clients with push-admin privileges and will be used more extensively in the future with smart notifications., platform: str(ios/android/browser) # Platform of the push device., deviceSecret: str # Secret value for the device., push.recipient: map{transportType: str, deviceToken: str, registrationToken: str, encryptionKey: map, clientId: str, deviceId: str} # Push recipient details for a device., push.state: str(Active/Failing/Failed) # the current state of the push device.}
@returns(2XX) {id: str, clientId: str, formFactor: str, metadata: map, platform: str, deviceSecret: str, push.recipient: map{transportType: str, deviceToken: str, registrationToken: str, encryptionKey: map, clientId: str, deviceId: str}, push.state: str} # OK

@endpoint PATCH /push/deviceRegistrations/{device_id}
@desc Update a device registration
@required {device_id: str # Device's ID.}
@optional {id: str # Unique identifier for the device generated by the device itself., clientId: str # Optional trusted client identifier for the device., formFactor: str(phone/tablet/desktop/tv/watch/car/embedded) # Form factor of the push device., metadata: map # Optional metadata object for this device. The metadata for a device may only be set by clients with push-admin privileges and will be used more extensively in the future with smart notifications., platform: str(ios/android/browser) # Platform of the push device., deviceSecret: str # Secret value for the device., push.recipient: map{transportType: str, deviceToken: str, registrationToken: str, encryptionKey: map, clientId: str, deviceId: str} # Push recipient details for a device., push.state: str(Active/Failing/Failed) # the current state of the push device.}
@returns(2XX) {id: str, clientId: str, formFactor: str, metadata: map, platform: str, deviceSecret: str, push.recipient: map{transportType: str, deviceToken: str, registrationToken: str, encryptionKey: map, clientId: str, deviceId: str}, push.state: str} # OK

@endpoint DELETE /push/deviceRegistrations/{device_id}
@desc Unregister a single device for push notifications
@required {device_id: str # Device's ID.}
@returns(2XX) OK

@endpoint GET /push/deviceRegistrations/{device_id}/resetUpdateToken
@desc Reset a registered device's update token
@required {device_id: str # Device's ID.}
@returns(2XX) {id: str, clientId: str, formFactor: str, metadata: map, platform: str, deviceSecret: str, push.recipient: map{transportType: str, deviceToken: str, registrationToken: str, encryptionKey: map, clientId: str, deviceId: str}, push.state: str} # OK

@endpoint GET /push/channelSubscriptions
@desc List channel subscriptions
@optional {channel: str # Filter to restrict to subscriptions associated with that channel., deviceId: str # Optional filter to restrict to devices associated with that deviceId. Cannot be used with clientId., clientId: str # Optional filter to restrict to devices associated with that clientId. Cannot be used with deviceId., limit: int=100 # The maximum number of records to return.}
@returns(2XX) {id: str, clientId: str, formFactor: str, metadata: map, platform: str, deviceSecret: str, push.recipient: map{transportType: str, deviceToken: str, registrationToken: str, encryptionKey: map, clientId: str, deviceId: str}, push.state: str} # OK

@endpoint POST /push/channelSubscriptions
@desc Subscribe a device to a channel
@returns(2XX) OK
@example_request {"channel":"my:channel","clientId":"myClientId"}

@endpoint DELETE /push/channelSubscriptions
@desc Delete a registered device's update token
@optional {channel: str # Filter to restrict to subscriptions associated with that channel., deviceId: str # Must be set when clientId is empty, cannot be used with clientId., clientId: str # Must be set when deviceId is empty, cannot be used with deviceId.}
@returns(2XX) OK

@endpoint GET /push/channels
@desc List all channels with at least one subscribed device
@returns(2XX) OK

@endpoint POST /push/publish
@desc Publish a push notification to device(s)
@required {recipient: map{transportType: str, deviceToken: str, registrationToken: str, encryptionKey: map, clientId: str, deviceId: str} # Push recipient details for a device.}
@optional {push: map{data: str, notification: map, apns: map, fcm: map, web: map}}
@returns(2XX) OK

@endgroup

@group keys
@endpoint POST /keys/{keyName}/requestToken
@desc Request an access token
@required {keyName: str # 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.}
@returns(2XX) {token: str, keyName: str, issued: int, expires: int, capability: str} # OK
@example_request {"keyName":"YourKey.Name","timestamp":"1559124196551","capability":{"channel1":["publish","subscribe"],"wildcard:channels:*":["publish"]}}

@endgroup

@group stats
@endpoint GET /stats
@desc Retrieve usage statistics for an application
@optional {start: str, limit: int=100, end: str=now, direction: str(forwards/backwards)=backwards, unit: str(minute/hour/day/month)=minute # Specifies the unit of aggregation in the returned results.}
@returns(2XX) OK

@endgroup

@group time
@endpoint GET /time
@desc Get the service time
@returns(2XX) OK

@endgroup

@end