Skip to main content
This walkthrough takes you from zero to reading compiled patient state: create an API key, register a patient, send a log, and query the result. It assumes your organization is already provisioned; if not, start with Setup.
1

Create an API key

In the Console, go to Settings → API Keys and create a key with the sdk:event-log, api:manage-patients, and sdk:state-read scopes. Or use the CLI:
olira keys create --name "quickstart" \
  --scopes sdk:event-log api:manage-patients sdk:state-read
Send your API key as a Bearer token in the Authorization header on every request:
Authorization: Bearer YOUR_OLIRA_API_KEY
API keys are shown only once at creation. Store them in an environment variable or secrets manager, never in source control.
2

Install the SDK and initialize

pip install olira

import os
import olira

olira.init(api_key=os.environ["OLIRA_API_KEY"])
3

Register a patient

Olira assigns the patient ID. Persist it in your database and use it for all future calls.
patient = olira.create_patient(
    first_name="Ada",
    last_name="Example",
    email="ada@example.com",
    external_identifiers=[{"system": "mrn", "value": "MRN-12345"}],
)
patient_id = patient.id
4

Send your first log

Every log has a type and a structured payload. Send a symptom report via the SDK or plain HTTP:
from olira import OliraLogType

olira.log(
    log_type=OliraLogType.SYMPTOM_REPORT,
    patient_id=patient_id,
    payload={
        "instrument": "esas_r",
        "symptoms": [
            {"name": "pain", "score": 4},
            {"name": "fatigue", "score": 6},
        ],
    },
)
olira.flush()
Olira validates the log_type and payload against the catalog, writes the record, and updates the patient’s state. See How logs work for the full submission fields.
5

Read compiled state

Query the patient’s compiled state (stable data, event-state modules, and logs) with the same SDK:
# Structured symptom state compiled from your logs
module = olira.get_event_state_module(
    patient_id=patient_id,
    module_type="symptoms",
)
print(module)

# Or the raw logs you just sent
logs = olira.get_logs(patient_id=patient_id, log_types=["symptom_report"])
print(logs.count)
Agent runtimes can read the same state over the MCP Patient State server.

​
Next steps

Logging from your codebase

Wire your backend to the SDK: batch patient creation, traces, and verification.

Accessing patient state

Choose between MCP, SDK, and REST for downstream workflows.

Log types catalog

Payload schemas and required fields for every supported log type.

Historical backfill

Load months or years of past data in one controlled job.