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

# Introduction

> Overview of the OSVI AI REST API

## Base URL

All API requests are made to:

```
https://api.osvi.ai
```

## Authentication

Every request must include your API token in the `API-Token` header:

```http theme={null}
API-Token: <your-api-token>
```

You can find your API token in the OSVI dashboard under **Settings → API**.

<Note>
  Your API token is 16 characters long and scoped to your account. Keep it secret — do not expose it in client-side code.
</Note>

## Request Format

All request bodies must be JSON. Set the `Content-Type` header accordingly:

```http theme={null}
Content-Type: application/json
```

## Response Format

All responses return JSON. Successful responses follow this shape:

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

Error responses:

```json theme={null}
{
  "success": false,
  "errors": ["field is required"]
}
```

## HTTP Status Codes

| Code  | Meaning                                                          |
| ----- | ---------------------------------------------------------------- |
| `200` | Success                                                          |
| `401` | Unauthorized — invalid or missing `API-Token`                    |
| `404` | Resource not found                                               |
| `422` | Validation error — check the `errors` array in the response body |
| `500` | Internal server error                                            |

## Agent UUID

Most endpoints require an `agent_uuid`. This is the unique identifier for your OSVI agent, formatted as:

```
agent_<alphanumeric-string>
```

Find your agent UUID in the OSVI dashboard on the agent's detail page. The session-scoped chat control endpoints (support and inject-context) instead address a session by its `id`.

## Agents API

Use [`GET /v1/active_agents`](/api-reference/endpoint/active_agents) to list the agents on your account that are currently active and able to take calls — handy for validating an `agent_uuid` before triggering a call.

## Calls API

Use [`POST /v1/call`](/api-reference/endpoint/call_v1) to start an outbound phone call. Only `agent_uuid`, `phone_number`, and `country_code` are required; every other field is optional.

Read results back without waiting for a webhook:

* [List calls](/api-reference/endpoint/list_calls) (`GET /v1/calls`) with filters for status, agent, campaign, date range, and phone number.
* [Get a call](/api-reference/endpoint/get_call) (`GET /v1/call/{id}`) for its summary, extracted data, and analysis — the same payload post-call webhooks deliver.
* Fetch the [transcript](/api-reference/endpoint/call_transcript) or a presigned [recording URL](/api-reference/endpoint/call_recording).

## Campaigns API

* [Add contacts](/api-reference/endpoint/campaign_add_contacts) (`POST /v1/campaigns/{id}/contacts`) to push a contact list into a campaign and optionally start calling immediately — no manual CSV upload.
* [Get campaign status](/api-reference/endpoint/campaign_status) (`GET /v1/campaigns/{id}/status`) for call outcomes and queue progress.

## Do Not Disturb API

Manage the numbers an agent must never call: [add](/api-reference/endpoint/dnd_add), [list](/api-reference/endpoint/dnd_list), and [remove](/api-reference/endpoint/dnd_remove) entries under `/v1/dnd_numbers`. Opt-outs propagate to the calling engine immediately, so they apply to in-flight campaigns.

## Chat API

The **Chat (v1)** endpoints under `/v1/chat/*` are the current way to run text conversations with an agent. A typical flow is:

1. [Create a session](/api-reference/endpoint/chat/create_session) for a customer (optional — sending a message will resolve or create one).
2. [Send messages](/api-reference/endpoint/chat/send_message) with `POST /v1/chat/inbound` and read the agent's `reply`.
3. Use [support commands](/api-reference/endpoint/chat/support) for human takeover, and [inject context](/api-reference/endpoint/chat/inject_context) to add out-of-band information mid-conversation.

<Warning>
  The endpoints under the **Legacy** section — `POST /call`, `/chat_sessions`, and `/chat_messages/send_message` — are still available but will be deprecated soon. Build new integrations on the **API v1** endpoints (`POST /v1/call` and `/v1/chat/*`).
</Warning>