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)

Example Request

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:

{
  "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:

{
  "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 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:

{
  "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	Manage virtual phone numbers
Call	Initiate and control calls
Call Flows	Manage IVR call flows
Extensions	Manage internal extensions
SIP Trunks	Manage SIP trunk connections
SIP Accounts	Manage SIP accounts
Teams	Manage agent teams
Agents	Manage call center agents
Voice Agents	Manage AI voice agents
Audios	Manage audio files
Webhooks	Manage webhook endpoints

Agent API

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

Resource	Description
Roles & Permissions	Team roles (member, leader, supervisor) & permission matrix
Authentication	Agent login, JWT verify, token refresh & password recovery
Account	Profile, teams, avatar, devices & logout
Realtime Events	Server-Sent Events (SSE) stream for presence, queue & notifications
Outbound Calls	Initiate outbound calls via REST & native WebSockets per-call
Contacts	Manage contacts — create, search, lookup & delete
Address Books	Organize contacts into named address books
Teams	View teams, teammates, agent states & team management
Phone Numbers	View phone numbers available to your teams
Call History	View calls you handled as an agent
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.