# API reference

> How every VoiceLayer API request works, and where to find each endpoint.

Source: https://docs.vlayers.ai/reference

Kind: Reference

The VoiceLayer API is a JSON REST API. Every endpoint has its own page in this section, with its parameters, a request in curl, TypeScript and Python, and an example response.

## Make a request

The base URL is `https://api.vlayers.ai`, and every route is under `/v1`. Send your API key as a bearer token:

cURL:

```bash
curl https://api.vlayers.ai/v1/channels \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
```

TypeScript:

```ts
import { createVoiceLayerClient, listChannels } from '@voicelayer/api';

const client = createVoiceLayerClient({ apiKey: process.env.VOICELAYER_API_KEY!, throwOnError: true });

const { data } = await listChannels({
  client
});
console.log(data.channels);
```

Python:

```python
import os
import voicelayer

config = voicelayer.Configuration(access_token=os.environ["VOICELAYER_API_KEY"])
with voicelayer.ApiClient(config) as client:
    api = voicelayer.ChannelsApi(client)
    result = api.list_channels()
    print(result.channels)
```

Create keys in the dashboard under **Developers → API keys**. See [Authentication and API keys](https://docs.vlayers.ai/get-started/authentication) for test and live keys and their scopes.

## Conventions

- **JSON in, JSON out.** Send `Content-Type: application/json` with a body. Every answer is JSON, except the event stream, which is Server-Sent Events.
- **Ids** are opaque strings. Store them as you receive them.
- **Times** are ISO 8601 in UTC, for example `2026-10-20T15:04:05.000Z`.
- **Sends are accepted, not delivered.** A send answers `202 Accepted`; delivery arrives later as events.
- **New fields appear without notice.** Ignore fields and enum values you do not know.

## The OpenAPI document

The whole API is described by one OpenAPI 3.1 document at [/openapi.json](https://docs.vlayers.ai/openapi.json). Load it into your API client or a code generator. The SDKs are generated from it.

## Errors

A refused request answers an HTTP error status and a JSON body:

```json
{
  "error": "window_closed",
  "message": "The 24-hour reply window for this conversation is closed.",
  "requestId": "req-8f2c1d4b",
  "retryable": false,
  "docs": "https://docs.vlayers.ai/errors/window_closed"
}
```

`error` is a stable code: branch on it, not on `message`. Every code has a page in [Error codes](https://docs.vlayers.ai/errors).

## Everything else

| Topic | Page |
|---|---|
| Retrying safely with `Idempotency-Key` | [Errors, retries and idempotency](https://docs.vlayers.ai/developers/errors-and-retries) |
| Cursors and page sizes | [Pagination](https://docs.vlayers.ai/developers/pagination) |
| Requests per minute | [Rate limits](https://docs.vlayers.ai/developers/rate-limits) |
| Versions and what changed | [Changelog and versioning](https://docs.vlayers.ai/changelog) |
| Real-time events | [Webhooks](https://docs.vlayers.ai/developers/receive/webhooks), [event stream](https://docs.vlayers.ai/developers/receive/event-stream) |