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

# API reference

> Endpoints, mounts, response envelopes, pagination, and status codes.

## Endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/api/v1/chat/create` | Start a chat with a caregiver |
| `GET` | `/api/v1/chat/{chat_id}` | Read one chat and its history |
| `POST` | `/api/v1/chat/message` | Send a message and wait for the reply |
| `POST` | `/api/v1/chat/message/stream` | Send a message and stream the reply as server-sent events |
| `POST` | `/api/v1/chat/end` | End a chat session |
| `POST` | `/api/calls/make-outbound` | Start a phone call from an owned number |
| `POST` | `/api/calls/web/register` | Register a browser voice call and issue a LiveKit token |
| `GET` | `/api/calls` | List calls owned by the organization |
| `GET` | `/api/calls/{call_id}` | Read one call |
| `GET` | `/api/chats/sessions` | List chat sessions owned by the organization |
| `GET` | `/api/chats/sessions/{chat_id}` | Read one chat result |
| `GET` | `/api/calls/recording/{call_id}` | Download an authorized recording |

Every request needs an organization API key; see
[Authentication](https://docs.drivehealth.ai/authentication.md).

## API origin

Use the API origin supplied for your environment. Production examples use
`https://backend.drivehealth.ai`. Paths include the `/api` prefix.

## Mounts

The v1 chat API answers on two prefixes:

* `/api/v1/chat/...` (recommended)
* `/v1/chat/...` (compatibility mount)

They are the same views. A prefix is not a credential and does not change what
a caller reaches. Every other route lives under `/api` only.

## Responses

Mutation and detail responses use the standard envelope:

```json theme={null}
{ "err": false, "msg": "Success", "results": { } }
```

```json theme={null}
{ "err": true, "msg": "Chat session not found" }
```

Ownership failures read as "not found" on purpose: whether a record exists in
another organization is not something a caller is told.

Requests refused before the endpoint runs (an invalid or revoked key, no
credential, more than one credential, or a selector for another organization)
return `403 Forbidden` with a `detail` message instead of the envelope:

```json theme={null}
{ "detail": "Unauthorized" }
```

## Pagination

List responses use page-number pagination directly. Pass `page` (starting at 1)
and `limit` (default 10):

```json theme={null}
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [{ "call_id": "3c2b1a09-8f7e-4d6c-9b8a-7d6c5b4a3f2e" }]
}
```

## Status codes

| Status | Meaning |
| - | - |
| `200` | Request completed, including chat creation |
| `201` | Web-call registration created |
| `400` | Invalid input, a record your organization does not own, or a call precondition failed |
| `403` | Refused before the endpoint ran: an invalid or revoked key, no credential, more than one credential, an endpoint organization keys cannot use, or a selector that conflicts with the key |
| `412` | Web-call registration only: the caregiver was not found in the key's organization |

Download the [OpenAPI specification](https://docs.drivehealth.ai/openapi/backend.json) to generate a
client or import the reference into your tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.