> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ably/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

The Ably REST API provides direct HTTP access to the Ably service for publishing messages, querying history, managing authentication, and more. While we recommend using the [REST SDK](/docs/api/rest-sdk) for most applications, the REST API is available for scenarios where an SDK is not available or practical.

## Overview

The REST API enables you to:

* Publish messages to channels
* Retrieve message and presence history
* Request authentication tokens
* Query channel metadata and statistics
* Manage push notifications
* Perform batch operations

## Base URL

All REST API requests use the following base URL:

<Code>
  ```text theme={null}
  https://rest.ably.io
  ```
</Code>

For enterprise customers, custom endpoints may be available.

## Authentication

The REST API supports two authentication methods:

### Basic Authentication

Use your API key in the Authorization header:

<Code>
  ```shell theme={null}
  curl https://rest.ably.io/channels/my-channel/messages \
    -u "{{API_KEY}}"
  ```
</Code>

### Token Authentication

Use an Ably Token or JWT in the Authorization header:

<Code>
  ```shell theme={null}
  curl https://rest.ably.io/channels/my-channel/messages \
    --header "Authorization: Bearer {{TOKEN}}"
  ```
</Code>

Learn more about [authentication](/docs/auth).

## Core Endpoints

### Publishing Messages

Publish messages to a channel:

<Code>
  ```shell theme={null}
  curl -X POST https://rest.ably.io/channels/my-channel/messages \
    -u "{{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "event-name",
      "data": "message payload"
    }'
  ```
</Code>

### Message History

Retrieve message history:

<Code>
  ```shell theme={null}
  curl https://rest.ably.io/channels/my-channel/messages \
    -u "{{API_KEY}}"
  ```
</Code>

### Presence

Query current presence:

<Code>
  ```shell theme={null}
  curl https://rest.ably.io/channels/my-channel/presence \
    -u "{{API_KEY}}"
  ```
</Code>

### Authentication Tokens

Request an Ably Token:

<Code>
  ```shell theme={null}
  curl -X POST https://rest.ably.io/keys/{{API_KEY_NAME}}/requestToken \
    -u "{{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "ttl": 3600000,
      "capability": "{\"*\":[\"*\"]}"
    }'
  ```
</Code>

## Request Format

### Content Types

The API accepts the following content types:

* `application/json` - JSON (default)
* `application/x-msgpack` - MessagePack (binary)
* `application/x-www-form-urlencoded` - Form-encoded

### Response Format

Specify the response format using the Accept header or format parameter:

* `application/json` - JSON (default)
* `application/x-msgpack` - MessagePack (binary)
* `application/javascript` - JSONP
* `text/html` - HTML

## Pagination

APIs with potentially large result sets return paginated responses:

<Code>
  ```shell theme={null}
  curl https://rest.ably.io/channels/my-channel/messages?limit=100 \
    -u "{{API_KEY}}"
  ```
</Code>

Pagination links are provided in the response headers.

## Rate Limits

The REST API has rate limits to ensure fair usage:

* Message publish: Up to 2,000 messages per second per account
* History queries: Up to 50 requests per second per account
* Token requests: Up to 50 requests per second per account

See [rate limits](/docs/platform/pricing/limits) for full details.

## Error Handling

Errors return standard HTTP status codes with error details:

<Code>
  ```json theme={null}
  {
    "error": {
      "code": 40140,
      "message": "Token expired",
      "statusCode": 401
    }
  }
  ```
</Code>

Common status codes:

* `400` - Bad Request (invalid parameters)
* `401` - Unauthorized (invalid credentials)
* `403` - Forbidden (insufficient permissions)
* `404` - Not Found (resource not found)
* `429` - Too Many Requests (rate limited)
* `500` - Internal Server Error

## API Reference Sections

<Tiles>
  {[
    {
      title: 'Channel API',
      description: 'Publish messages and query channels',
      link: '/docs/api/rest-api#channel',
    },
    {
      title: 'Authentication API',
      description: 'Request and manage authentication tokens',
      link: '/docs/api/rest-api#authentication',
    },
    {
      title: 'Push API',
      description: 'Manage push notification subscriptions',
      link: '/docs/api/rest-api#push',
    },
    {
      title: 'Stats API',
      description: 'Query application usage statistics',
      link: '/docs/api/rest-api#stats',
    },
    ]}
</Tiles>

## Related Resources

* [REST SDK](/docs/api/rest-sdk)
* [SSE API](/docs/api/sse)
* [Control API](/docs/api/control-api)
* [Authentication Guide](/docs/auth)