> ## Documentation Index
> Fetch the complete documentation index at: https://docs.typelessapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Core conventions shared by every Typeless API endpoint — base URL, authentication, response shape, and status codes.

## Base URL

```
https://api.typelessapi.com/v1
```

All traffic is HTTPS only; streaming uses WSS.

## Authentication

Pass your API key in the `Authorization` header for HTTP requests:

```
Authorization: Token <key>
```

For WebSocket connections, pass the key as the `token` query parameter in the connection URL.

See [Authentication](/authentication) for full details and key management.

## Response envelope

Every response — success or error — shares a common envelope structure.

**Success**

```json theme={null}
{
  "status": "success",
  "result": { "transcript": "Let's move the launch to next Thursday and loop in the design team early.", "detected_language": "en", "duration_seconds": 42.5 },
  "usage": { "billed_audio_seconds": 42.5, "output_token_count": 128 },
  "request_id": "01JXXXXXXXXXXXXXXXXXXXXXXX"
}
```

**Error**

```json theme={null}
{
  "status": "error",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "model is required"
  },
  "request_id": "01JXXXXXXXXXXXXXXXXXXXXXXX"
}
```

The `error.details` field may appear on validation errors to provide per-field context; it is optional and omitted when not applicable.

## Request IDs

Every response includes a `request_id` — a 26-character ULID that uniquely identifies your request. Include it when contacting support; it lets us trace your exact request through our systems.

## HTTP status codes

| Status | Meaning                                                                    |
| ------ | -------------------------------------------------------------------------- |
| 200    | Success                                                                    |
| 400    | Invalid request — missing/invalid parameters or unsupported audio format   |
| 401    | Authentication failed — missing or invalid API key                         |
| 402    | Insufficient balance — top up in the console                               |
| 403    | Account suspended                                                          |
| 413    | Payload too large — file exceeds 50 MB or audio exceeds the duration limit |
| 429    | Rate limit or concurrency limit exceeded                                   |
| 500    | Server error — safe to retry once; report with `request_id` if persistent  |
| 503    | Service temporarily unavailable — retry with backoff                       |

For full error codes and handling guidance, see [Errors](/reference/errors).