# API reference

The API serves real-time transcription: create a session over HTTP, stream its audio over a WebSocket.

## Base URL

| region | |
|---|---|
| Europe | `https://eu1.api.gladia.io` |
| United States | `https://us1.api.gladia.io` |

Use the region of your account ([Regions](/introduction/regions/)).

## Authentication

Send your API key in the `x-gladia-key` header ([Authentication](/introduction/authentication/)):

```bash
curl https://eu1.api.gladia.io/v2/live/defaults -H "x-gladia-key: $GLADIA_API_KEY"
```

## Endpoints

| | |
|---|---|
| [`POST /v2/live`](/api-reference/v2/live/init/) | Create a session, get its WebSocket URL |
| [WebSocket `/v2/live?token=…`](/api-reference/v2/live/websocket/) | Stream the audio, receive the messages |
| [`GET /v2/live/{id}`](/api-reference/v2/live/get/) | A session and its result |
| [`GET /v2/live`](/api-reference/v2/live/list/) | Your sessions |
| [`GET /v2/live/{id}/file`](/api-reference/v2/live/get-audio/) | A session's recording |
| [`DELETE /v2/live/{id}`](/api-reference/v2/live/delete/) | Delete a session |
| [`GET /v2/live/defaults`](/api-reference/v2/live/defaults/) | The values of omitted options |

Every page has a **Try it** panel that calls the API with your key, from your browser.

## Errors

Errors answer with a JSON body:

```json
{
  "statusCode": 400,
  "timestamp": "2026-10-12T09:04:17.210Z",
  "path": "/v2/live",
  "message": "Invalid parameter(s). See validation_errors for more details.",
  "request_id": "G-1a2b3c4d",
  "validation_errors": ["sample_rate Input should be 8000, 16000, 32000, 44100 or 48000"]
}
```

| status | meaning |
|---|---|
| `400` | The request is invalid: `validation_errors` says why. |
| `401` | No API key, or an unknown one. |
| `403` | The key may not do this: its scopes, or the caller's address (`error` gives the reason). |
| `404` | No such session for your account. |
| `429` | Your account has its maximum number of sessions open ([Limits](/limits/concurrency/)). |
| `500` | No model in this region runs the session as asked: its model, its languages and its features together (`no inference endpoint available`), or none has room right now. |
| `503` | The service is busy: retry with backoff. |

Quote `request_id` when you contact support.

## OpenAPI

The whole API is described in [/openapi.json](/openapi.json) (OpenAPI 3.1), including the WebSocket messages
(`x-websocket`): generate a client, or import it in your API tool.