canonical: https://jentic.com/apis/ably.io/ably-platform # Ably Platform API The Ably Platform API is the broader REST surface for Ably's realtime platform, covering pub/sub messaging on channels plus the full push notification stack. It exposes 22 endpoints across messages, presence, push device registrations, channel subscriptions, and push publish, alongside token issuance for client auth. The spec is published in Ably's open-specs repository, so the schema tracks the live platform. Use it when a server needs to publish, audit history, or manage push subscriptions without standing up a WebSocket. ## For AI agents Publish realtime messages, manage push device registrations and channel subscriptions, and issue auth tokens via Ably's Platform REST API. ## Scope Does not handle account-level app or key provisioning, queue management, or integration rules - use the Ably Control API for those, and Platform API for messages, presence, and push. ## Capabilities - Publish messages to a channel and fetch message history - Read channel presence and presence history - Register a device for push notifications and update its registration - Subscribe a device to push notifications on specific channels - List channels with at least one subscribed device - Publish a push notification directly to specific devices - Issue short-lived Ably tokens scoped by capability ## Use cases ### Mobile Push Notification Delivery Mobile apps register devices with Ably so backends can push notifications without dealing with APNs and FCM directly. POST /push/deviceRegistrations registers the device, POST /push/channelSubscriptions binds it to a channel, and POST /push/publish or POST /channels/{channel_id}/messages with push extras delivers the payload. The full flow stays inside one platform API. Example prompt: Register device 'd-123' for push, subscribe it to channel 'alerts', and publish a push message 'New alert' to that channel ### Realtime Pub/Sub from a Backend Server-side workloads publish events to Ably channels for fan-out to web and mobile clients. POST /channels/{channel_id}/messages handles the publish, GET /channels lists active channels, and GET /channels/{channel_id}/messages retrieves history. This pattern is suited to dashboards, multi-user editing, and live ops alerts. Example prompt: Publish a JSON event to channel 'orders' and fetch the last 50 messages for verification ### Push Subscription Inventory Operations teams need visibility on which channels have active push subscribers and which devices belong to a given user. The push endpoints support listing channels with subscribers, fetching individual device registrations, and patching them to update tokens. This keeps push hygiene under control as devices churn. Example prompt: List all channels with push subscribers and fetch the device registration for device ID 'd-123' ### Agent-Driven Push and Pub/Sub via Jentic AI agents that orchestrate notifications can drive Ably's Platform API as a tool. Through Jentic, an agent searches by intent, loads the matching push or messages operation, and executes with the API key from your Jentic One instance. This lets the agent register devices, subscribe them, and publish in sequence without juggling SDKs. Example prompt: Search Jentic for 'send a push notification', load the Ably push schema, and execute the publish call with the channel and payload ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /channels/{channel_id}/messages | Publish a message to a channel | | GET | /channels/{channel_id}/messages | Get message history for a channel | | POST | /push/deviceRegistrations | Register a device for push notifications | | POST | /push/channelSubscriptions | Subscribe a device to a channel | | POST | /push/publish | Publish a push notification to devices | | GET | /push/channels | List channels with subscribed devices | | POST | /keys/{keyName}/requestToken | Request a short-lived Ably token | ## Key resources - **Channels** — Publish messages, fetch history, list active channels, and read metadata - **Presence** — Read current presence and presence history on a channel - **Device Registrations** — Register, update, and unregister push-enabled devices - **Channel Subscriptions** — Subscribe and unsubscribe devices on push channels - **Push Publish** — Publish a push notification directly to specific devices or channels - **Keys** — Issue short-lived Ably tokens scoped by capability ## Why Jentic - **Setup:** Wiring the Platform API by hand means managing its Ably key with either HTTP Basic or bearer auth, targeting the rest.ably.io host, and shaping message and push payloads yourself. Through Jentic you install once, import the Platform API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** The Platform API puts the channel id in the URL path (/channels/{channel_id}/messages), so a rule can pin your agent to one channel for publishing and history. You choose the operations it may call, so push device registration or publishing is not included unless you add it. - **Credential handling:** Your Ably API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'publish a message to a channel' or 'register a device for push', and Jentic returns the matching Platform API operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Ably REST API** — Slimmer REST surface for Ably channels, presence, history, and tokens. - **Ably Control API** — Manage Ably apps, keys, queues, and rules at the account level. - **OneSignal** — OneSignal's push notification platform across mobile and web. - **PubNub** — PubNub realtime platform with messaging, presence, and push. ## FAQ ### What authentication does the Ably Platform API use? The API supports HTTP Basic auth (using the Ably API key) and bearer token auth via tokens issued by POST /keys/{keyName}/requestToken. Through Jentic, both schemes are stored in your Jentic One instance and applied at execution time, so the agent never holds the raw key. ### Can I send push notifications with the Ably Platform API? Yes. Register devices via POST /push/deviceRegistrations, bind them to a channel with POST /push/channelSubscriptions, and publish via POST /push/publish or POST /channels/{channel_id}/messages with push extras. List active push channels with GET /push/channels. ### How do I register a mobile device for push through Jentic? Search Jentic for 'register a device for push notifications' to find POST /push/deviceRegistrations, load the schema, and execute the call with the device platform, token, and client ID. Jentic injects the Ably credential from the vault. ### What are the rate limits for the Ably Platform API? Rate limits are not encoded in the spec; Ably enforces them per account based on the active plan. Inspect message volumes via the stats surface and check the Ably account dashboard for the current ceiling. On 429 responses, back off and retry with jitter. ### How do I unregister a push device when a user signs out? Call DELETE /push/deviceRegistrations/{device_id} for a single device, or DELETE /push/deviceRegistrations with a query filter to unregister matching devices in bulk. Pair with DELETE /push/channelSubscriptions to clean up subscriptions before the device disappears. ### Is the Platform API the same as the REST API? The Platform API is a superset of the REST surface: it includes the same channels, messages, presence, and key endpoints, plus the push device registrations, subscriptions, and push publish endpoints. Pick the Platform API when push notifications are in scope, the REST API when only pub/sub and token issuance are needed. ### Can I limit what my agent is allowed to do with the Ably Platform API? Yes. Because you run Jentic One yourself, your own rules decide which Ably Platform operations and credentials the agent may use. Since the channel id sits in the URL path, such as /channels/{channel_id}/messages, a rule can pin the agent to a single channel for publishing and history. You also choose the operations it may call, so push device registration via POST /push/deviceRegistrations or publishing via POST /push/publish is excluded unless you explicitly allow it.