# REST API

> The /v1 REST API: base URL, authentication, scopes and every operation.

Source: https://docs.voice.kheelona.com/reference/generated/api/

The REST API lives at `https://api.voice.kheelona.com`. All paths start with `/v1`. Requests and responses are JSON.

## Authentication

`Authorization: Bearer kv_live_…`: a partner API key, created in your Kheelona console. Server-to-server only; never ship it to a browser or a device. Revocation takes effect within 60 s.

Every response carries an `X-Request-Id` header. Errors use one shape (see [Errors](https://docs.voice.kheelona.com/reference/generated/errors.md)).

## Scopes

An API key carries the scopes it was created with; an operation needs the scope shown.

| Scope | Operations |
| --- | --- |
| `sessions:read` | [`listSessions`](https://docs.voice.kheelona.com/reference/generated/api/listsessions.md), [`getSession`](https://docs.voice.kheelona.com/reference/generated/api/getsession.md) |
| `sessions:write` | [`createSession`](https://docs.voice.kheelona.com/reference/generated/api/createsession.md), [`endSession`](https://docs.voice.kheelona.com/reference/generated/api/endsession.md) |
| `usage:read` | [`getUsage`](https://docs.voice.kheelona.com/reference/generated/api/getusage.md) |
| `voices:read` | [`listVoices`](https://docs.voice.kheelona.com/reference/generated/api/listvoices.md), [`getVoice`](https://docs.voice.kheelona.com/reference/generated/api/getvoice.md) |

## Operations

### sessions

Create sessions, read the connection log, end sessions

| Operation | Endpoint | Summary |
| --- | --- | --- |
| [`listSessions`](https://docs.voice.kheelona.com/reference/generated/api/listsessions.md) | `GET /v1/sessions` | The partner's connection log, newest first. |
| [`createSession`](https://docs.voice.kheelona.com/reference/generated/api/createsession.md) | `POST /v1/sessions` | Creates a session. |
| [`getSession`](https://docs.voice.kheelona.com/reference/generated/api/getsession.md) | `GET /v1/sessions/{id}` | One of the partner's sessions. |
| [`endSession`](https://docs.voice.kheelona.com/reference/generated/api/endsession.md) | `POST /v1/sessions/{id}/end` | Ends a live session (reason `partner_ended`; the live connection closes within 10 s) or cancels a reserved one. Ending a finished session is a no-op. |

### voices

The voices enabled for your partner

| Operation | Endpoint | Summary |
| --- | --- | --- |
| [`listVoices`](https://docs.voice.kheelona.com/reference/generated/api/listvoices.md) | `GET /v1/voices` | The voices enabled for this partner. |
| [`getVoice`](https://docs.voice.kheelona.com/reference/generated/api/getvoice.md) | `GET /v1/voices/{id}` | One voice. |

### languages

The supported languages

| Operation | Endpoint | Summary |
| --- | --- | --- |
| [`listLanguages`](https://docs.voice.kheelona.com/reference/generated/api/listlanguages.md) | `GET /v1/languages` | The supported languages. |

### usage

Usage for invoicing and cost analysis

| Operation | Endpoint | Summary |
| --- | --- | --- |
| [`getUsage`](https://docs.voice.kheelona.com/reference/generated/api/getusage.md) | `GET /v1/usage` | Usage for the key's partner. |

### health

Service health

| Operation | Endpoint | Summary |
| --- | --- | --- |
| [`getHealth`](https://docs.voice.kheelona.com/reference/generated/api/gethealth.md) | `GET /v1/health` | The service's health. |