Where to start

A condition story is a pre-assembled Markdown narrative for a single clinical condition. It combines onset, current medications, monitoring labs, and complications from the knowledge graph into a single document, so an agent can get full context in one read.

Find the condition slug

Browse the active conditions to get the slug:

curl "https://api.<workspace-id>.clinia.cloud/patients/{patientId}/vfs?path=/conditions/active" \
  -H "X-Clinia-API-Key: <clinia-api-key>"

Each child name is the condition slug, derived from the primary display name, lowercased, with spaces replaced by underscores.

Read via REST

curl "https://api.<workspace-id>.clinia.cloud/patients/{patientId}/read?path=/conditions/active/{condition}/_story.md" \
  -H "X-Clinia-API-Key: <clinia-api-key>"

The response is { "content": "..." } where content is the Markdown narrative.

Read via MCP tool

read_patient(
  path = "/patient/{patientId}/conditions/active/{condition}/_story.md"
)

Choosing a format

Pass format to control verbosity. Default is narrative.

# Compact format
curl "https://api.<workspace-id>.clinia.cloud/patients/{patientId}/read?path=/conditions/active/{condition}/_story.md&format=compact" \
  -H "X-Clinia-API-Key: <clinia-api-key>"

# Structured format
curl "https://api.<workspace-id>.clinia.cloud/patients/{patientId}/read?path=/conditions/active/{condition}/_story.md&format=structured" \
  -H "X-Clinia-API-Key: <clinia-api-key>"

Setting a token budget

Pass token_budget to cap response length. The renderer prioritises content in this order before truncating:

1. Current status and onset
2. Active medications
3. Recent labs
4. Complications and their monitoring status
5. Historical details and source provenance

curl "https://api.<workspace-id>.clinia.cloud/patients/{patientId}/read?path=/conditions/active/{condition}/_story.md&token_budget=300" \
  -H "X-Clinia-API-Key: <clinia-api-key>"

One token ≈ 4 characters. A budget of 300 gives roughly a paragraph-length narrative. Omit token_budget for no limit.

What a story contains

A full narrative story includes:

• Status: active / resolved, onset date
• Codes: SNOMED, ICD-10 codes from all sources
• Sources: how many source documents contributed to this entity
• Current treatment: medications with prescribed_for relationship to this condition
• Monitoring labs: labs with monitors relationship, latest values and whether in range
• Complications: conditions with complication_of relationship, their monitoring status
• Provenance: which resolver matched this entity and at what confidence

Complications and their monitoring status come from the clinical knowledge base. They are not extracted directly from the source records.

Read the raw entity

For machine-readable fields without the narrative formatting, read _raw.json:

curl "https://api.<workspace-id>.clinia.cloud/patients/{patientId}/read?path=/conditions/active/{condition}/_raw.json" \
  -H "X-Clinia-API-Key: <clinia-api-key>"

See Condition Stories for a full explanation of how stories are assembled.