---
sidebar_position: 1
title: Overview
description: Overview of the Firetell REST API — base URL, request format, versioning, error codes, and pagination.
---

# REST API Overview

The Firetell REST API allows you to programmatically manage your cloud communications infrastructure.

## Base URL

Each workspace has its own API domain:

```
https://{workspace_id}.firetell.app/api/v1
```

Replace `{workspace_id}` with your workspace's subdomain (found in **Console** → **Workspace Settings** → **General**).

All endpoints are relative to this base URL.

## Request Format

- All requests use **HTTPS**
- Request bodies must be **JSON** with `Content-Type: application/json`
- Authentication via `Authorization` header — `ApiKey sk-...` for Workspace API or `Bearer <jwt>` for Agent API (see [Authentication](/docs/getting-started/authentication))

### Example Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/phone-numbers" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

## Response Format

All responses return JSON. Successful responses include a `data` field:

```json
{
  "data": [{
    ...
  }],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "total_pages": 5
  }
}
```

## HTTP Status Codes

| Code  | Description                               |
| ----- | ----------------------------------------- |
| `200` | Success                                   |
| `201` | Resource created                          |
| `400` | Bad request — invalid parameters          |
| `401` | Unauthorized — invalid or missing API key |
| `403` | Forbidden — insufficient permissions      |
| `404` | Resource not found                        |
| `429` | Rate limit exceeded                       |
| `500` | Internal server error                     |

## Error Response Format

When a request fails validation (HTTP `400`), the API returns a structured error body describing every invalid field:

```json
{
  "statusCode": 400,
  "message": "name must not be empty",
  "error": "Bad Request",
  "errors": [
    {
      "field": "name",
      "messages": ["name must not be empty", "name must be a string"]
    },
    {
      "field": "address.city",
      "messages": ["city must be a string"]
    }
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The first validation message — convenient for simple error display |
| `errors` | `array` | Full list of all invalid fields |
| `errors[].field` | `string` | Dot-notation path to the invalid field (e.g. `address.city` for nested objects) |
| `errors[].messages` | `string[]` | All constraint violation messages for that field |

:::tip
Use `errors` to map validation feedback directly to form fields. The top-level `message` is kept for backward compatibility and quick display.
:::

## Pagination

List endpoints support pagination with the following query parameters:

| Parameter | Type   | Default | Description                  |
| --------- | ------ | ------- | ---------------------------- |
| `page`    | number | `1`     | Page number                  |
| `limit`   | number | `20`    | Items per page (max 100)     |
| `search`  | string | —       | Text search filter           |
| `sort`    | string | —       | Sort field                   |
| `order`   | string | `desc`  | Sort order (`asc` or `desc`) |

## Rate Limiting

All API endpoints are rate-limited to protect the platform and ensure fair usage. Rate limits are enforced per minute using a fixed-window counter backed by Firetell servers.

### Rate Limit Tiers

| Tier        | Limit       | Endpoints                                      |
| ----------- | ----------- | ---------------------------------------------- |
| **Default** | 100 req/min | All standard API endpoints                     |
| **Auth**    | 10 req/min  | `/auth/login`, `/auth/verify`, `/auth/refresh` |
| **Heavy**   | 30 req/min  | Upload, resource-intensive operations          |

Rate limits are applied **per API Key** when using API Key authentication, **per agent IP** when using agent JWT authentication (`agent-api`), or **per client identifier** when using client JWT authentication (`client-api`).

:::note
**Need higher limits?**

Enterprise customers can request custom rate limits. Contact us at [enterprise@firetell.com](mailto:enterprise@firetell.com) with your workspace ID and use case.
:::

### Response Headers

Every response includes rate limit information:

| Header                  | Description                                     |
| ----------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the window          |
| `X-RateLimit-Remaining` | Requests remaining in the current window        |
| `Retry-After`           | Seconds to wait before retrying (only on `429`) |

### Rate Limit Exceeded (429)

When the rate limit is exceeded, the API returns a `429 Too Many Requests` response:

```json
{
  "statusCode": 429,
  "message": "Rate limit exceeded. Please try again later.",
  "retryAfter": 42
}
```

:::tip
**Best Practices**

- **Implement exponential backoff** when receiving `429` responses
- **Cache responses** to reduce API calls
- **Use webhooks** instead of polling for real-time updates
- Monitor the `X-RateLimit-Remaining` header to preemptively slow down
  :::

## Available Resources

### Workspace API

Management endpoints for workspace administrators. Authenticated via `ApiKey`.

| Resource                                                    | Description                  |
| ----------------------------------------------------------- | ---------------------------- |
| [Phone Numbers](/docs/rest-api/workspace-api/phone-numbers) | Manage virtual phone numbers |
| [Call](/docs/rest-api/workspace-api/call)                   | Initiate and control calls   |
| [Call Flows](/docs/rest-api/workspace-api/call-flows)       | Manage IVR call flows        |
| [Extensions](/docs/rest-api/workspace-api/extensions)       | Manage internal extensions   |
| [SIP Trunks](/docs/rest-api/workspace-api/sip-trunks)       | Manage SIP trunk connections |
| [SIP Accounts](/docs/rest-api/workspace-api/sip-accounts)   | Manage SIP accounts          |
| [Teams](/docs/rest-api/workspace-api/teams)                 | Manage agent teams           |
| [Agents](/docs/rest-api/workspace-api/agents)               | Manage call center agents    |
| [Voice Agents](/docs/rest-api/workspace-api/voice-agents)   | Manage AI voice agents       |
| [Audios](/docs/rest-api/workspace-api/audios)               | Manage audio files           |
| [Webhooks](/docs/rest-api/workspace-api/webhooks)           | Manage webhook endpoints     |

### Agent API

Call center portal endpoints for agents. Authenticated via agent JWT (`agent-api` audience).

| Resource                                                          | Description                                                         |
| ----------------------------------------------------------------- | ------------------------------------------------------------------- |
| [Roles & Permissions](/docs/rest-api/agent-api/roles-permissions) | Team roles (member, leader, supervisor) & permission matrix         |
| [Authentication](/docs/rest-api/agent-api/auth)                   | Agent login, JWT verify, token refresh & password recovery          |
| [Account](/docs/rest-api/agent-api/account)                       | Profile, teams, avatar, devices & logout                            |
| [Realtime Events](/docs/rest-api/agent-api/realtime-events)       | Server-Sent Events (SSE) stream for presence, queue & notifications |
| [Outbound Calls](/docs/rest-api/agent-api/calls)                  | Initiate outbound calls via REST & native WebSockets per-call       |
| [Contacts](/docs/rest-api/agent-api/contacts)                     | Manage contacts — create, search, lookup & delete                   |
| [Address Books](/docs/rest-api/agent-api/address-books)           | Organize contacts into named address books                          |
| [Teams](/docs/rest-api/agent-api/teams)                           | View teams, teammates, agent states & team management               |
| [Phone Numbers](/docs/rest-api/agent-api/phone-numbers)           | View phone numbers available to your teams                          |
| [Call History](/docs/rest-api/agent-api/call-history)             | View calls you handled as an agent                                  |
| [Call Supervision](/docs/rest-api/agent-api/call-supervision)     | Listen, whisper, barge (supervisor) & call transfer (all agents)    |

## Enterprise Services

Need advanced capabilities beyond the standard platform? Firetell offers custom enterprise solutions:

| Service                      | Description                                                                   |
| ---------------------------- | ----------------------------------------------------------------------------- |
| **Custom Rate Limits**       | Higher or tailored rate limits for your workload                              |
| **Custom Base Domain**       | Use your own domain instead of `*.firetell.app` (e.g., `api.yourcompany.com`) |
| **Dedicated Infrastructure** | Isolated deployment for compliance and performance                            |
| **Priority Support**         | Dedicated technical support and SLA guarantees                                |

To discuss enterprise requirements, contact us at [enterprise@firetell.com](mailto:enterprise@firetell.com).