canonical: https://jentic.com/apis/ably.com/ably

# Ably REST API

Jentic publishes the only available OpenAPI specification for Ably REST API, keeping it validated and agent-ready. The Ably REST API is the request/response interface to Ably's realtime messaging platform. It covers publishing messages to channels, retrieving message and presence history, listing active channels, requesting tokens for client authentication, and pulling application statistics. The eight endpoints are gated by HTTP Basic auth (with the API key) or a bearer token issued by /keys/{keyName}/requestToken, and complement Ably's realtime SDKs when a server-side workflow is enough.

## For AI agents

Publish messages to Ably channels, fetch history, manage tokens, and read application statistics over HTTP. Use it for server-side realtime publishing without a WebSocket connection.

## Scope

Does not handle WebSocket connections, app provisioning, or push-notification delivery - use for HTTP publishing, history, presence, and token issuance only.

## Capabilities

- Publish a message to a named Ably channel
- Pull message history for a channel with paging and filters
- Read the current presence set on a channel and its presence history
- List active channels in the application for monitoring
- Get channel metadata and current status
- Request an Ably token for short-lived, scoped client auth
- Retrieve application-level statistics (messages, peak connections)

## Use cases

### Server-Side Event Publishing

Backend services need to push realtime events (order updates, dashboard refreshes, alerts) without holding a persistent WebSocket. POST /channels/{channelId}/messages publishes from a server process to all connected subscribers, with delivery handled by Ably's global edge network. This is the simplest way to broadcast events from a job queue or webhook handler.

Example prompt: Publish a JSON message {orderId: 'A123', status: 'shipped'} to channel 'orders'

### Token-Based Client Auth

Browser and mobile clients should never embed a long-lived Ably API key. POST /keys/{keyName}/requestToken issues short-lived tokens scoped to the operations the client needs, so the front end connects with reduced blast radius if the token leaks. Pair with Ably realtime SDKs for the actual WebSocket connection.

Example prompt: Request an Ably token for keyName 'frontend' with capability {chat: ['publish','subscribe']} and a TTL of 600 seconds

### Message History and Auditing

Compliance and audit workflows replay or re-export realtime events. GET /channels/{channelId}/messages returns historical messages with paging, while GET /channels/{channelId}/presence/history reconstructs who was on the channel at any time. Application stats from /stats round out the picture for usage reporting.

Example prompt: Fetch the last 100 messages on channel 'orders' between 09:00 and 10:00 UTC for the audit log

### Agent-Driven Realtime Publishing via Jentic

AI agents can drive Ably without standing up SDK plumbing. Through Jentic, an agent searches for the publish intent, loads POST /channels/{channelId}/messages, and executes with the API key from your Jentic One instance. The same flow covers token issuance and history retrieval when an agent needs to reason about recent activity.

Example prompt: Search Jentic for 'publish a realtime message', load the Ably schema, and execute the call with channel and message body

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /channels/{channelId}/messages | Publish a message to a channel |
| GET | /channels/{channelId}/messages | Get message history for a channel |
| GET | /channels/{channelId}/presence | Get the current presence set |
| GET | /channels | List active channels |
| POST | /keys/{keyName}/requestToken | Request a short-lived Ably token |
| GET | /stats | Get application statistics |

## Key resources

- **Channels** — List active channels and inspect channel metadata
- **Messages** — Publish to a channel and fetch message history
- **Presence** — Read current presence set and presence history
- **Keys** — Issue short-lived Ably tokens scoped to capabilities
- **Stats** — Retrieve application-level usage statistics

## Why Jentic

- **Setup:** Wiring the Ably REST API by hand means managing its key with either HTTP Basic or bearer token auth, targeting the rest.ably.io host, and shaping message, presence, and token-request payloads yourself. Through Jentic you install once, import the Ably REST API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Ably puts the channel id in the URL path (/channels/{channelId}/messages), so a rule can pin your agent to one channel: it can publish and read history and presence for that channel and nothing else. You choose the operations it may call, so token issuance 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 realtime message' or 'read a channel's message history', and Jentic returns the matching Ably REST operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Ably Platform API** — The broader Ably Platform API including push device registrations and channel subscriptions.
- **Ably Control API** — Ably's Control API for managing apps, keys, namespaces, queues, and rules.
- **PubNub** — PubNub realtime messaging platform with publish, subscribe, presence, and history.
- **Pusher Channels** — Pusher Channels API for pub/sub messaging.

## FAQ

### Why is there no official OpenAPI spec for Ably REST API?

Ably publishes reference docs at ably.com/docs/api/rest-api but does not host a single discoverable OpenAPI specification for that surface. Jentic generates and maintains this spec so that AI agents and developers can call Ably REST API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Ably REST API use?

The API supports HTTP Basic auth using the Ably API key as the username, or bearer token auth using a token issued by POST /keys/{keyName}/requestToken. Through Jentic, both schemes are stored in the vault and applied at execution time, so neither value enters the agent's context.

### Can I publish messages to a channel with the Ably REST API?

Yes. POST /channels/{channelId}/messages publishes one or more messages to the named channel. The body accepts a single message or an array, and Ably distributes the payload to all connected subscribers via its realtime fabric.

### How do I fetch channel history through Jentic?

Search Jentic for 'get channel history' to find GET /channels/{channelId}/messages, load the schema, and execute the call with the channel ID and time bounds. The response is paged and returns messages in newest-first order by default.

### What are the rate limits for the Ably REST API?

The OpenAPI spec does not encode rate limits; Ably enforces them per account based on the active plan. Read GET /stats for live message counts and check the Ably account dashboard for the current limit. On 429s, back off and retry with jitter.

### How do I issue a short-lived token for a browser client?

Call POST /keys/{keyName}/requestToken with the desired capability JSON and TTL. The response is an Ably token request the front end can use to connect via the realtime SDK without ever holding the long-lived API key.

### Can I limit what my agent is allowed to do with the Ably REST API?

Yes. Because you run Jentic One yourself, your own rules decide which Ably operations and credentials the agent may use. Since Ably puts the channel id in the URL path (/channels/{channelId}/messages), you can pin the agent to a single channel so it only publishes and reads history and presence for that channel and nothing else. You also pick the operations it may call, so token issuance via POST /keys/{keyName}/requestToken is excluded unless you explicitly allow it.