> ## 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.

# Control API

The Ably Control API is a REST API that enables you to programmatically manage your Ably account. Use the Control API to automate the provisioning, configuration, and management of your Ably apps, API keys, queues, and integration rules.

## Overview

The Control API enables you to:

* Create, update, and delete Ably apps
* Manage API keys and their capabilities
* Configure namespaces and channel rules
* Set up queues and integration rules
* Query account and app statistics
* Automate multi-tenant deployments

## When to Use Control API

The Control API is ideal for:

* Automating app provisioning and configuration
* Building multi-tenant SaaS applications
* Creating configuration-driven environments
* Programmatic testing and CI/CD pipelines
* Building administrative tools and dashboards

## Getting Started

### Authentication

The Control API uses Bearer token authentication. First, create an access token in the [Ably dashboard](https://ably.com/dashboard):

1. Select your account from the top menu
2. Choose **My Access Tokens**
3. Click **Create new access token**
4. Select the required capabilities
5. Copy the generated token

Use the token in the Authorization header:

<Code>
  ```shell theme={null}
  curl https://control.ably.net/v1/me \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```
</Code>

### Base URL

All Control API requests use:

<Code>
  ```text theme={null}
  https://control.ably.net/v1
  ```
</Code>

## Core Resources

### Apps

Manage Ably applications:

<Code>
  ```shell theme={null}
  # List all apps
  curl https://control.ably.net/v1/accounts/ACCOUNT_ID/apps \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

  # Create a new app
  curl -X POST https://control.ably.net/v1/accounts/ACCOUNT_ID/apps \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "My New App",
      "status": "enabled",
      "tlsOnly": true
    }'
  ```
</Code>

### API Keys

Manage API keys for your apps:

<Code>
  ```shell theme={null}
  # List keys for an app
  curl https://control.ably.net/v1/apps/APP_ID/keys \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

  # Create a new API key
  curl -X POST https://control.ably.net/v1/apps/APP_ID/keys \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Server Key",
      "capability": {"*":["*"]}
    }'
  ```
</Code>

### Namespaces

Configure channel rules using namespaces:

<Code>
  ```shell theme={null}
  # Create a namespace
  curl -X POST https://control.ably.net/v1/apps/APP_ID/namespaces \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "id": "persisted",
      "persisted": true
    }'
  ```
</Code>

### Queues

Manage message queues:

<Code>
  ```shell theme={null}
  # List queues
  curl https://control.ably.net/v1/apps/APP_ID/queues \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

  # Create a queue
  curl -X POST https://control.ably.net/v1/apps/APP_ID/queues \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "my-queue",
      "ttl": 60,
      "maxLength": 10000
    }'
  ```
</Code>

### Rules

Configure integration rules:

<Code>
  ```shell theme={null}
  # List rules
  curl https://control.ably.net/v1/apps/APP_ID/rules \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

  # Create a webhook rule
  curl -X POST https://control.ably.net/v1/apps/APP_ID/rules \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "ruleType": "http",
      "source": {
        "channelFilter": "^events:.*",
        "type": "channel.message"
      },
      "target": {
        "url": "https://example.com/webhook"
      }
    }'
  ```
</Code>

## Resource Identifiers

### Account ID

Find your account ID in the dashboard:

1. Select your account from the top menu
2. Choose **Account settings**
3. Copy the Account ID

### App ID

Find your app ID in the dashboard:

1. Select your app
2. Go to the **Settings** tab
3. Copy the App ID (also the first part of your API key)

## Statistics

Query usage statistics:

<Code>
  ```shell theme={null}
  # Account-level statistics
  curl "https://control.ably.net/v1/accounts/ACCOUNT_ID/stats?unit=hour&limit=24" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

  # App-level statistics
  curl "https://control.ably.net/v1/apps/APP_ID/stats?unit=hour&limit=24" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```
</Code>

## Error Handling

The Control API returns standard HTTP status codes:

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

Common status codes:

* `200` - Success
* `201` - Created
* `400` - Bad Request
* `401` - Unauthorized
* `403` - Forbidden
* `404` - Not Found
* `429` - Too Many Requests
* `500` - Internal Server Error

## Rate Limits

The Control API has rate limits:

* Standard operations: 100 requests per minute
* Statistics queries: 20 requests per minute

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

## OpenAPI Specification

The Control API is documented using OpenAPI 3.0. Download the specification from the [Ably OpenAPI repository](https://github.com/ably/open-specs).

Use the specification to:

* Generate client libraries
* Import into API testing tools (Postman, Insomnia)
* Create mock servers
* Generate documentation

## Examples

### Multi-Tenant App Provisioning

Automate app creation for each tenant:

<Code>
  ```javascript theme={null}
  async function provisionTenant(tenantName) {
    const response = await fetch(
      `https://control.ably.net/v1/accounts/${ACCOUNT_ID}/apps`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${ACCESS_TOKEN}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          name: `${tenantName} App`,
          status: 'enabled',
          tlsOnly: true
        })
      }
    );
    
    return await response.json();
  }
  ```
</Code>

### Configuration Replication

Copy configuration from one app to another:

<Code>
  ```javascript theme={null}
  async function replicateConfig(sourceAppId, targetAppId) {
    // Get source app configuration
    const sourceKeys = await getKeys(sourceAppId);
    const sourceNamespaces = await getNamespaces(sourceAppId);
    const sourceRules = await getRules(sourceAppId);
    
    // Apply to target app
    for (const key of sourceKeys) {
      await createKey(targetAppId, key);
    }
    
    for (const namespace of sourceNamespaces) {
      await createNamespace(targetAppId, namespace);
    }
    
    for (const rule of sourceRules) {
      await createRule(targetAppId, rule);
    }
  }
  ```
</Code>

## Related Resources

* [Control API User Guide](/docs/platform/account/control-api)
* [OpenAPI Specification](https://github.com/ably/open-specs)
* [Authentication Guide](/docs/auth)
* [Integration Rules](/docs/platform/integrations)
* [Queues Documentation](/docs/platform/integrations/queues)