Manage a Session

This walks through the interactive session lifecycle: record conversation turns under a session ID of your choosing as they happen, follow the ingestion each one queues, then confirm what landed in the patient's record.

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

Choose a session id

Pick a session ID you control — for example, one from your own chat infrastructure. There is no call to open the session: its first write does, and every later write under the same ID adds to it. The patient must already exist, and the ID has to fit the character set for identifiers you assign.

Record each turn

After each turn, send the conversation so far under the session ID. The first call creates the session. Only user and assistant roles are accepted.

curl -X POST "https://<workspace-id>.w.clinia.cloud/v1/patients/{patientId}/ingestions/sessions" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "sessions": [
      {
        "sessionId": "session-456",
        "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." }
        ]
      }
    ]
  }'

The call answers 202 with an ingestion receipt. Memories are formed from the new turns as that ingestion is processed: there is no separate step to trigger it.

Resend the whole conversation each time, with the new turns at the end. Turns already stored are recognised and not stored again, so only the new ones count toward staged.messages. Resending the whole conversation also keeps a turn that repeats an earlier one, such as a second "yes", from being mistaken for it. See Ingest Sessions for the full rules.

Follow the ingestion

Poll the receipt's ingestionId until status is succeeded, partial or failed:

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

You only need to poll when your application has to read the memories straight away. Otherwise they appear on their own.

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": "lm_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.