# API overview

The Turnix API is a small JSON API. Most integrations only need one endpoint: [`POST /credentials/ice`](https://turnix.io/docs/api-reference/credentials).

## Base URL

```text
https://turnix.io/api/v1
```

The version is part of the path. `GET /api/v1` returns `{"api_version": 1}`.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | [`/credentials/ice`](https://turnix.io/docs/api-reference/credentials) | Create ICE credentials (STUN + TURN) |
| `GET` | [`/regions`](https://turnix.io/docs/api-reference/regions) | List TURN regions |
| `GET` | [`/usage/current`](https://turnix.io/docs/api-reference/usage#get-usage-current) | Current plan, billing period and traffic |
| `GET` | [`/usage/list_periods`](https://turnix.io/docs/api-reference/usage#get-usage-list_periods) | Traffic for all billing periods |
| `GET` | [`/ltc/key`](https://turnix.io/docs/integrations/shared-secret#manage-the-secret-via-the-api) | Read the project's auth secret |
| `POST` | [`/ltc/rotate`](https://turnix.io/docs/integrations/shared-secret#manage-the-secret-via-the-api) | Rotate the project's auth secret |

## Authentication

Send a project API token as a Bearer token on every request:

```http
Authorization: Bearer YOUR_API_TOKEN
```

The token identifies your organization and project, so you never pass their IDs. See [Authentication](https://turnix.io/docs/api-reference/authentication).

## Requests and responses

- Request bodies can be JSON (`Content-Type: application/json`) or form-encoded (`application/x-www-form-urlencoded`). All body parameters are optional.
- Responses are JSON. Timestamps are ISO 8601 in UTC, for example `2026-10-30T13:00:00.000Z`.
- Use HTTPS. Call the API from your backend only.

## Errors

Errors return a non-2xx status and a JSON body with an `error` message. Some errors add a `code` or extra fields:

```json
{ "error": "Token not found", "code": "unauthorized" }
```

| Status | Meaning | Examples |
|--------|---------|----------|
| `400` | A required parameter is missing | `{"error":"Required parameter missing: …"}` |
| `401` | Not authenticated, or the organization has no subscription | `Not Authorized`, `Token not found`, `You are not on any subscription` |
| `422` | A parameter is invalid or the request cannot be fulfilled | `TTL must be an integer`, `room contains invalid characters`, `Specified Region Not Found`, `Region Offline` |
| `429` | Your organization reached its data usage limit | `Usage limit exceeded` (see [Usage, limits & billing](https://turnix.io/docs/concepts/usage-limits)) |
| `5xx` | Something went wrong on our side | Retry with backoff |

Match on the HTTP status, not on the exact message text.

## Limits

- **Usage limit:** on plans without overage, `POST /credentials/ice` returns `429` once the organization's traffic for the billing period reaches the plan's allowance. See [Usage, limits & billing](https://turnix.io/docs/concepts/usage-limits).
- **Rate limit:** none is currently enforced. Request credentials once per connection.