> ## 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.

# Chat

> Start a chat with a caregiver, exchange messages, and end the session.

A chat session connects your application to one of your organization's
caregivers. Create a session, send messages with its `chat_id`, read it back at
any time, and end it when the conversation is over.

The chat routes answer on `/api/v1/chat/...` (recommended) and on the
compatibility mount `/v1/chat/...`. They are the same views; a prefix is not a
credential and does not change what a caller reaches. The examples use
`/api/v1`.

## Create a session

```http theme={null}
POST /api/v1/chat/create
Authorization: Bearer dh_your_api_key
Content-Type: application/json

{ "assistant_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d" }
```

```json theme={null}
{
  "err": false,
  "msg": "Success",
  "results": { "chat_id": "9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f" }
}
```

The caregiver must belong to your organization. The session it creates is
owned by that same organization and appears in the
[chat results](https://docs.drivehealth.ai/results.md#chats).

## Send a message

```http theme={null}
POST /api/v1/chat/message
Authorization: Bearer dh_your_api_key
Content-Type: application/json

{ "chat_id": "9f8e7d6c-...", "message": "What time is my appointment?" }
```

```json theme={null}
{
  "err": false,
  "msg": "Success",
  "results": {
    "response": "Your appointment is on Thursday at 2pm.",
    "chat_id": "9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f"
  }
}
```

## Stream a reply

```http theme={null}
POST /api/v1/chat/message/stream
Authorization: Bearer dh_your_api_key
Content-Type: application/json

{ "chat_id": "9f8e7d6c-...", "message": "What time is my appointment?" }
```

The response is `Content-Type: text/event-stream`, with one JSON object per
`data:` frame:

```text theme={null}
data: {"chunk": "Your appointment is ", "chat_id": "9f8e7d6c-..."}

data: {"chunk": "on Thursday at 2pm.", "chat_id": "9f8e7d6c-..."}

data: {"done": true, "chat_id": "9f8e7d6c-..."}
```

The credential and the chat's ownership are resolved *before* the stream
opens, so a refused request gets an ordinary error response, not a `200` whose
first frame says no. Once the stream is open, only model failures appear inside
it, as `{"error": "LLM error", "chat_id": "..."}` followed by the end of the
stream.

> [!WARNING]
>
> The transcript is written when the stream completes. A client that abandons
> the stream (a browser tab closing, or an `AbortController` firing on logout
> or an organization switch) leaves the turn unrecorded.

## Read a session

```http theme={null}
GET /api/v1/chat/9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f
Authorization: Bearer dh_your_api_key
```

```json theme={null}
{
  "err": false,
  "msg": "Success",
  "results": {
    "chat_id": "9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f",
    "assistant_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "assistant_name": "Appointments",
    "status": "active",
    "user_message_count": 1,
    "assistant_message_count": 2,
    "history": [
      { "role": "assistant", "content": "Hello, how can I help?" },
      { "role": "user", "content": "What time is my appointment?" },
      { "role": "assistant", "content": "Your appointment is on Thursday at 2pm." }
    ]
  }
}
```

## End a session

```http theme={null}
POST /api/v1/chat/end
Authorization: Bearer dh_your_api_key
Content-Type: application/json

{ "chat_id": "9f8e7d6c-..." }
```

```json theme={null}
{ "err": false, "msg": "Chat ended" }
```

Ending marks the session; it does not erase it. The transcript stays readable.


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