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

# API Overview

> Kallglot API v1 reference documentation

# API Reference

Use this section to reproduce working requests: URLs, bodies, authentication, pagination, errors, and the WebSocket stream. It is intentionally limited to what you need to connect your servers and clients to Kallglot.

The API follows common REST patterns: JSON over HTTPS, standard status codes, and Bearer API keys.

## Base URL

All API endpoints are relative to:

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

## Request Format

The API accepts JSON-encoded request bodies and returns JSON-encoded responses. All requests must include the `Content-Type: application/json` header for POST/PUT/PATCH requests.

```bash theme={null}
curl https://api.kallglot.com/v1/sessions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"mode": "bidirectional_translation"}'
```

## Response Format

All responses follow a consistent structure:

### Success Response

```json theme={null}
{
  "id": "sess_01HXYZ123456789",
  "object": "session",
  "status": "created",
  "created_at": "2026-03-26T10:00:00Z"
}
```

### Error Response

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "The 'mode' field is required.",
    "type": "validation_error",
    "param": "mode"
  }
}
```

## Object Types

| Object          | Description                          |
| --------------- | ------------------------------------ |
| `session`       | A real-time voice processing session |
| `agent`         | Configurable AI agent                |
| `transcript`    | Text transcript of a session         |
| `recording`     | Audio recording of a session         |
| `analysis`      | AI analysis of a session             |
| `webhook_event` | Event delivered via webhook          |

## ID Formats

All objects use prefixed identifiers for easy identification:

| Prefix  | Object Type                           |
| ------- | ------------------------------------- |
| `sess_` | Session                               |
| `rec_`  | Recording                             |
| `anl_`  | Analysis                              |
| `agt_`  | AI agent (ids are issued by Kallglot) |
| `kst_`  | Stream token                          |
| `wh_`   | Webhook endpoint                      |
| `evt_`  | Webhook event                         |

## Pagination

There is **no** `GET /v1/sessions` list endpoint. Cursor-style query parameters apply only where a list route exists:

* `GET /v1/agents`
* `GET /v1/sessions/{session_id}/recordings`

```bash theme={null}
curl "https://api.kallglot.com/v1/agents?limit=20&starting_after=agt_01HXYZ"
```

| Parameter        | Type    | Description                                      |
| ---------------- | ------- | ------------------------------------------------ |
| `limit`          | integer | Page size (`1`–`100`; default `20`)              |
| `starting_after` | string  | Cursor for forward pagination                    |
| `ending_before`  | string  | Cursor for backward pagination (where supported) |

### Paginated list response shape

```json theme={null}
{
  "object": "list",
  "data": [{ "id": "agt_01HXYZ", "object": "agent", "name": "Support" }],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/agents"
}
```

## Idempotency

For POST requests that create resources, include an `Idempotency-Key` header to ensure the request is processed only once:

```bash theme={null}
curl -X POST https://api.kallglot.com/v1/sessions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -H "Content-Type: application/json" \
  -d '{"mode": "bidirectional_translation"}'
```

* Keys are valid for roughly 24 hours (server-defined TTL)
* Retrying with the same key returns the cached response **when** the JSON body matches the original request (see mismatches below)
* Use UUIDs or other unique identifiers

See [Idempotency](/concepts/idempotency) for supported routes, conflict codes, and body-matching behavior.

## Versioning

The API version is included in the URL path (`/v1/`). We release new versions when making backwards-incompatible changes.

| Version | Status  | End of Life |
| ------- | ------- | ----------- |
| v1      | Current | -           |

## Endpoints

### Agents

| Method   | Endpoint         | Description          |
| -------- | ---------------- | -------------------- |
| `GET`    | `/v1/agents`     | List AI agents       |
| `GET`    | `/v1/agents/:id` | Retrieve an AI agent |
| `POST`   | `/v1/agents`     | Create an AI agent   |
| `PATCH`  | `/v1/agents/:id` | Update an AI agent   |
| `DELETE` | `/v1/agents/:id` | Delete an AI agent   |

### Sessions

| Method | Endpoint                      | Description                                                                                                                                |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST` | `/v1/sessions`                | Create a new session                                                                                                                       |
| `GET`  | `/v1/sessions/:id`            | Retrieve a session                                                                                                                         |
| `POST` | `/v1/sessions/:id/end`        | End a session                                                                                                                              |
| `POST` | `/v1/sessions/:id/dial`       | Start an outbound SIP dial (use [Create Session](/api-reference/sessions/create) with SIP `routing`; session is typically `created` first) |
| `POST` | `/v1/sessions/:id/hangup`     | Hang up an active SIP leg                                                                                                                  |
| `GET`  | `/v1/sessions/:id/transcript` | Get session transcript                                                                                                                     |
| `GET`  | `/v1/sessions/:id/recordings` | List session recordings                                                                                                                    |

### Recordings

| Method | Endpoint                   | Description                 |
| ------ | -------------------------- | --------------------------- |
| `GET`  | `/v1/recordings/:id`       | Retrieve recording metadata |
| `GET`  | `/v1/recordings/:id/audio` | Download recording audio    |

### Analysis

| Method | Endpoint                    | Description                             |
| ------ | --------------------------- | --------------------------------------- |
| `POST` | `/v1/sessions/:id/analysis` | Queue session analysis (`202 Accepted`) |
| `GET`  | `/v1/analyses/:id`          | Retrieve analysis results               |

### Streaming

| Protocol  | Endpoint                                                   | Description                              |
| --------- | ---------------------------------------------------------- | ---------------------------------------- |
| WebSocket | `wss://api.kallglot.com/v1/sessions/:id/connect?token=...` | Real-time audio and transcript streaming |