Agent chat endpoints

Authentication

Send one of the following in the Authorization header. Clerk session JWTs are not accepted on these routes.

• •Bearer <encounter_token> — the 64-char hex token returned from POST /api/v1/agent/query. Scoped to a single encounter. Expires 72 hours after the encounter was created.
• •Bearer ak_<your-api-key> — the patient's personal API key. Must belong to the encounter's owner.

Poll for messages

Rate-limited to 12 polls/minute per encounter. Returns 429 with a Retry-After header when exceeded.

Query parameters

Example

curl "$API/api/v1/agent/encounters/$ENCOUNTER_ID/events?since=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer $ENCOUNTER_TOKEN"

Response

{
  "encounterId": "a1b2c3d4-...",
  "state": "waitingForPatientReply",
  "events": [
    {
      "eventId": "...",
      "authorId": "...",
      "author": { "id": "...", "email": "dr.smith@appendix.com", "clinician": { "firstName": "Anna", "lastName": "Smith", "credentials": "MD" } },
      "type": "chat",
      "message": "How has the cough progressed since last week?",
      "createdAt": "2026-03-02T10:15:00Z",
      "source": "web",
      "isOwn": false
    }
  ]
}

source is "web" when a human typed the message, or "api" when it was posted via this API. isOwn is true when the message was authored by the patient — via either the web UI or this API.

Reply on the patient's behalf

Posts a chat message to the clinician. Returns 409 if the encounter hasn't been claimed yet (the patient must complete checkout first).

Request body

Example

curl -X POST "$API/api/v1/agent/encounters/$ENCOUNTER_ID/events" \
  -H "Authorization: Bearer $ENCOUNTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Thanks, I will pick up the prescription today."}'

Mark messages read

Record a read receipt on behalf of the patient. Once recorded, the patient will not receive an email reminder about that clinician message.

Request body

Errors