{"files":{"SKILL.md":"---\nname: platform-api\ndescription: \"Platform API skill. Use when working with Platform for channels, push, keys. Covers 22 endpoints.\"\nversion: 1.0.0\ngenerator: lapsh\n---\n\n# Platform API\nAPI version: 1.1.1\n\n## Auth\nBearer basic | Bearer bearer\n\n## Base URL\nhttps://rest.ably.io\n\n## Setup\n1. Set Authorization header with Bearer token\n2. GET /channels -- enumerate all active channels of the application\n3. POST /channels/{channel_id}/messages -- create first message\n\n## Endpoints\n22 endpoints across 5 groups. See references/api-spec.lap for full details.\n\n### Channels\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /channels/{channel_id}/messages | Get message history for a channel |\n| POST | /channels/{channel_id}/messages | Publish a message to a channel |\n| GET | /channels/{channel_id}/presence | Get presence of a channel |\n| GET | /channels/{channel_id}/presence/history | Get presence history of a channel |\n| GET | /channels/{channel_id} | Get metadata of a channel |\n| GET | /channels | Enumerate all active channels of the application |\n\n### Push\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /push/deviceRegistrations | List devices registered for receiving push notifications |\n| POST | /push/deviceRegistrations | Register a device for receiving push notifications |\n| DELETE | /push/deviceRegistrations | Unregister matching devices for push notifications |\n| GET | /push/deviceRegistrations/{device_id} | Get a device registration |\n| PUT | /push/deviceRegistrations/{device_id} | Update a device registration |\n| PATCH | /push/deviceRegistrations/{device_id} | Update a device registration |\n| DELETE | /push/deviceRegistrations/{device_id} | Unregister a single device for push notifications |\n| GET | /push/deviceRegistrations/{device_id}/resetUpdateToken | Reset a registered device's update token |\n| GET | /push/channelSubscriptions | List channel subscriptions |\n| POST | /push/channelSubscriptions | Subscribe a device to a channel |\n| DELETE | /push/channelSubscriptions | Delete a registered device's update token |\n| GET | /push/channels | List all channels with at least one subscribed device |\n| POST | /push/publish | Publish a push notification to device(s) |\n\n### Keys\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /keys/{keyName}/requestToken | Request an access token |\n\n### Stats\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /stats | Retrieve usage statistics for an application |\n\n### Time\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /time | Get the service time |\n\n## Common Questions\nMatch user requests to endpoints in references/api-spec.lap. Key patterns:\n- \"List all messages?\" -> GET /channels/{channel_id}/messages\n- \"Create a message?\" -> POST /channels/{channel_id}/messages\n- \"List all presence?\" -> GET /channels/{channel_id}/presence\n- \"List all history?\" -> GET /channels/{channel_id}/presence/history\n- \"Get channel details?\" -> GET /channels/{channel_id}\n- \"List all channels?\" -> GET /channels\n- \"List all deviceRegistrations?\" -> GET /push/deviceRegistrations\n- \"Create a deviceRegistration?\" -> POST /push/deviceRegistrations\n- \"Get deviceRegistration details?\" -> GET /push/deviceRegistrations/{device_id}\n- \"Update a deviceRegistration?\" -> PUT /push/deviceRegistrations/{device_id}\n- \"Partially update a deviceRegistration?\" -> PATCH /push/deviceRegistrations/{device_id}\n- \"Delete a deviceRegistration?\" -> DELETE /push/deviceRegistrations/{device_id}\n- \"List all resetUpdateToken?\" -> GET /push/deviceRegistrations/{device_id}/resetUpdateToken\n- \"List all channelSubscriptions?\" -> GET /push/channelSubscriptions\n- \"Create a channelSubscription?\" -> POST /push/channelSubscriptions\n- \"Create a publish?\" -> POST /push/publish\n- \"Create a requestToken?\" -> POST /keys/{keyName}/requestToken\n- \"List all stats?\" -> GET /stats\n- \"List all time?\" -> GET /time\n- \"How to authenticate?\" -> See Auth section above\n\n## Response Tips\n- Check response schemas in references/api-spec.lap for field details\n- Paginated endpoints accept limit/offset or cursor parameters\n- Create/update endpoints return the modified resource on success\n\n## References\n- Full spec: See references/api-spec.lap for complete endpoint details, parameter tables, and response schemas\n\n> Generated from the official API spec by [LAP](https://lap.sh)\n","references/api-spec.lap":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Platform API\n@base https://rest.ably.io\n@version 1.1.1\n@auth Bearer basic | Bearer bearer\n@endpoints 22\n@hint download_for_search\n@toc channels(6), push(13), keys(1), stats(1), time(1)\n\n@group channels\n@endpoint GET /channels/{channel_id}/messages\n@desc Get message history for a channel\n@required {channel_id: str # The [Channel's ID](https://www.ably.io/documentation/rest/channels).}\n@optional {start: str, limit: int=100, end: str=now, direction: str(forwards/backwards)=backwards}\n@returns(2XX) OK\n\n@endpoint POST /channels/{channel_id}/messages\n@desc Publish a message to a channel\n@required {channel_id: str # The [Channel's ID](https://www.ably.io/documentation/rest/channels).}\n@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.}\n@returns(2XX) {channel: str, messageId: str} # OK\n\n@endpoint GET /channels/{channel_id}/presence\n@desc Get presence of a channel\n@required {channel_id: str # The [Channel's ID](https://www.ably.io/documentation/rest/channels).}\n@optional {clientId: str, connectionId: str, limit: int=100}\n@returns(200) OK\n\n@endpoint GET /channels/{channel_id}/presence/history\n@desc Get presence history of a channel\n@required {channel_id: str # The [Channel's ID](https://www.ably.io/documentation/rest/channels).}\n@optional {start: str, limit: int=100, end: str=now, direction: str(forwards/backwards)=backwards}\n@returns(2XX) OK\n\n@endpoint GET /channels/{channel_id}\n@desc Get metadata of a channel\n@required {channel_id: str # The [Channel's ID](https://www.ably.io/documentation/rest/channels).}\n@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\n\n@endpoint GET /channels\n@desc Enumerate all active channels of the application\n@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)}\n@returns(2XX) OK\n\n@endgroup\n\n@group push\n@endpoint GET /push/deviceRegistrations\n@desc List devices registered for receiving push notifications\n@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.}\n@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\n\n@endpoint POST /push/deviceRegistrations\n@desc Register a device for receiving push notifications\n@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.}\n@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\n\n@endpoint DELETE /push/deviceRegistrations\n@desc Unregister matching devices for push notifications\n@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.}\n@returns(2XX) OK\n\n@endpoint GET /push/deviceRegistrations/{device_id}\n@desc Get a device registration\n@required {device_id: str # Device's ID.}\n@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\n\n@endpoint PUT /push/deviceRegistrations/{device_id}\n@desc Update a device registration\n@required {device_id: str # Device's ID.}\n@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.}\n@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\n\n@endpoint PATCH /push/deviceRegistrations/{device_id}\n@desc Update a device registration\n@required {device_id: str # Device's ID.}\n@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.}\n@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\n\n@endpoint DELETE /push/deviceRegistrations/{device_id}\n@desc Unregister a single device for push notifications\n@required {device_id: str # Device's ID.}\n@returns(2XX) OK\n\n@endpoint GET /push/deviceRegistrations/{device_id}/resetUpdateToken\n@desc Reset a registered device's update token\n@required {device_id: str # Device's ID.}\n@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\n\n@endpoint GET /push/channelSubscriptions\n@desc List channel subscriptions\n@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.}\n@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\n\n@endpoint POST /push/channelSubscriptions\n@desc Subscribe a device to a channel\n@returns(2XX) OK\n@example_request {\"channel\":\"my:channel\",\"clientId\":\"myClientId\"}\n\n@endpoint DELETE /push/channelSubscriptions\n@desc Delete a registered device's update token\n@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.}\n@returns(2XX) OK\n\n@endpoint GET /push/channels\n@desc List all channels with at least one subscribed device\n@returns(2XX) OK\n\n@endpoint POST /push/publish\n@desc Publish a push notification to device(s)\n@required {recipient: map{transportType: str, deviceToken: str, registrationToken: str, encryptionKey: map, clientId: str, deviceId: str} # Push recipient details for a device.}\n@optional {push: map{data: str, notification: map, apns: map, fcm: map, web: map}}\n@returns(2XX) OK\n\n@endgroup\n\n@group keys\n@endpoint POST /keys/{keyName}/requestToken\n@desc Request an access token\n@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.}\n@returns(2XX) {token: str, keyName: str, issued: int, expires: int, capability: str} # OK\n@example_request {\"keyName\":\"YourKey.Name\",\"timestamp\":\"1559124196551\",\"capability\":{\"channel1\":[\"publish\",\"subscribe\"],\"wildcard:channels:*\":[\"publish\"]}}\n\n@endgroup\n\n@group stats\n@endpoint GET /stats\n@desc Retrieve usage statistics for an application\n@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.}\n@returns(2XX) OK\n\n@endgroup\n\n@group time\n@endpoint GET /time\n@desc Get the service time\n@returns(2XX) OK\n\n@endgroup\n\n@end\n"}}