Manage a Session

This walks through the full interactive session lifecycle: open a session, append a few conversation turns, generate memories from them, then confirm what landed in the patient's record.

See Sessions for the underlying concepts, and Memory for what a memory is.

Open a session

Use PUT with a session ID you control (for example, one from your own chat infrastructure). It's idempotent: safe to call again with the same ID. The patient must already exist.

curl -X PUT "https://<workspace-id>.w.clinia.cloud/v1/patients/{patientId}/sessions/{sessionId}" \
  -H "Authorization: Bearer <access-token>"

{ "sessionId": "session-456", "patientId": "patient-123", "createdAt": "2026-07-27T14:02:11.000Z" }

To let the server generate the ID instead, use POST /v1/patients/{patientId}/sessions.

Append messages

Append each conversation turn as it happens. Only user and assistant roles are accepted.

curl -X POST "https://<workspace-id>.w.clinia.cloud/v1/patients/{patientId}/sessions/{sessionId}/messages" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "I stopped taking the Empagliflozin a few weeks ago, it was upsetting my stomach." },
      { "role": "assistant", "content": "Thanks for letting me know, I will flag that for your care team." }
    ]
  }'

{ "ok": true, "messageCount": 2 }

messageCount is the number of messages appended in this call, not the session's running total.

Generate memories

This is application-controlled: call it at whatever point your application considers the current interaction window over, rather than after every message. A common trigger is the user leaving the conversation or switching context, even if the conversation itself isn't formally "done."

curl -X POST "https://<workspace-id>.w.clinia.cloud/v1/patients/{patientId}/sessions/{sessionId}/memories" \
  -H "Authorization: Bearer <access-token>"

{ "ok": true }

The session stays open. You can keep appending messages, and call this endpoint again later: it extracts messages appended since the last extraction, so any new statements are appended as new memories.

List the memories a session produced

curl "https://<workspace-id>.w.clinia.cloud/v1/patients/{patientId}/sessions/{sessionId}/memories" \
  -H "Authorization: Bearer <access-token>"

{
  "data": [
    {
      "id": "tz4a98xxat96iws9zmbrgj3a",
      "type": "adherence",
      "content": "Stopped taking the Empagliflozin a few weeks ago, it was upsetting their stomach.",
      "sessionId": "session-456",
      "createdAt": "2026-07-27T14:03:02.000Z"
    }
  ],
  "meta": { "total": 1, "page": 0, "perPage": 100 }
}

Paginate with page and perPage, and sort with sort=createdAt&order=asc|desc (defaults to newest first).

Confirm it landed in the patient record

Read the memory type's VFS file to see it alongside any other memories of that type:

curl "https://<workspace-id>.w.clinia.cloud/v1/patients/{patientId}/read?path=/memory/adherence.md" \
  -H "Authorization: Bearer <access-token>"

If the memory matched a fact (as adherence and symptom memories can), it also shows up under a ## Patient-Reported heading on that fact's own page: the condition story for a condition, or the medication's file under /medications/current/{slug} for a medication.