Chat

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

POST /api/v1/chat/create
Authorization: Bearer dh_your_api_key
Content-Type: application/json

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

{
  "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.

Send a message

POST /api/v1/chat/message
Authorization: Bearer dh_your_api_key
Content-Type: application/json

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

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

Stream a reply

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:

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.

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

GET /api/v1/chat/9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f
Authorization: Bearer dh_your_api_key

{
  "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

POST /api/v1/chat/end
Authorization: Bearer dh_your_api_key
Content-Type: application/json

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

{ "err": false, "msg": "Chat ended" }

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

Get started

Use the API

Create a session

Send a message

Stream a reply

Read a session

End a session

​Create a session

​Send a message

​Stream a reply

​Read a session

​End a session

Create a session

Send a message

Stream a reply

Read a session

End a session