Encounters

Read your own encounters and the turns inside them. To start a new encounter use POST /api/v1/agent/query; to read or reply to physician chat use the agent chat endpoints.

All endpoints on this page require authentication (Clerk JWT or personal API key). They scope to the caller’s own encounters — a foreign encounter ID returns 404.

List your encounters

GET/api/v1/encounters

Returns an array of encounter summaries (no turns or events) for the authenticated user, ordered most-recent-first.

200 OK

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userId": "user-uuid",
    "patientId": "patient-uuid",
    "state": "submitted",
    "expiresAt": "2026-02-29T12:00:00Z",
    "createdAt": "2026-02-26T12:00:00Z",
    "updatedAt": "2026-02-26T12:01:00Z",
    "turnCount": 1,
    "submission": {
      "submissionId": "f0e9d8c7-...",
      "querySnapshot": "# Chief Complaint\n...",
      "createdAt": "2026-02-26T12:01:00Z"
    },
    "billing": { "type": "subscription", "amount": 0, "status": "completed" }
  }
]

Get encounter

GET/api/v1/encounters/{id}

Same shape as a list entry. Use this to poll the encounter’s state while the physician reviews. State machine: open → thinking → readyForCheckout → submitted → reviewing → completed → closed (after 72h).

List turns

GET/api/v1/encounters/{id}/turns

Returns every turn on the encounter — each turn pairs a query (the user’s letter) with the API’s evaluation response. Append ?last=N to fetch only the last N turns.

200 OK

{
  "turns": [
    {
      "turnId": "turn-uuid-1",
      "query": {
        "text": "# Chief Complaint\n...",
        "version": 1,
        "createdAt": "2026-02-26T12:00:00Z"
      },
      "response": {
        "evaluation": { "/* 11 booleans */": true },
        "options": [],
        "evidence": [],
        "createdAt": "2026-02-26T12:00:02Z"
      }
    }
  ]
}

Latest turn

GET/api/v1/encounters/{id}/latest-turn

Convenience endpoint for the most recent turn only. Useful when you’re polling and only care about the freshest evaluation.

Cancel encounter

POST/api/v1/encounters/{id}/cancel

Self-cancel a non-terminal encounter. Owner-only. Sends the encounter to the canceled state and prevents further turns or chat. Already-issued prescriptions are not recalled by this call (Photon owns the Rx record); cancellation stops review and stops further charges.

curl

curl -X POST https://api.appendix.com/api/v1/encounters/{id}/cancel \
  -H "Authorization: Bearer ak_..."

Errors

Code	Meaning
`401`	Missing or invalid credentials.
`404`	Encounter does not exist or belongs to another account.
`400`	On cancel: encounter is already in a terminal state and can’t be canceled.