Logging from your codebase

This guide assumes your organization, event types, and API keys are already configured (Console and/or CLI; see Setup). Here we wire your codebase to the Olira SDK: initialize the client, register one or many patients, and emit logs that drive patient state.

Install tooling

CLI (optional: keys, login, MCP config):

brew install olira-ai/tap/olira
# or: curl -fsSL https://install.olira.ai | sh

SDK (required for ingestion from your backend):

pip install olira
# or: uv add olira

dotnet add package Olira

Authenticate in your service

Use an API key with at least sdk:event-log and api:manage-patients for creating patients and logging. Create the key in the Console or with olira keys create (see the CLI key commands). Store it in a secret manager and pass it at runtime:

import os
import olira

olira.init(api_key=os.environ["OLIRA_API_KEY"])
# or set OLIRA_API_KEY and call olira.init()

using Olira;

OliraModule.Init(apiKey: Environment.GetEnvironmentVariable("OLIRA_API_KEY"));
// or set OLIRA_API_KEY and call OliraModule.Init()

Initialize the SDK and create patients

Single patient

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

var patient = OliraModule.CreatePatient(
    firstName: "Ada",
    lastName: "Example",
    email: "ada@example.com",
    externalIdentifiers:
    [
        new ExternalIdentifier { System = "mrn", Value = "MRN-12345" },
    ]);
var patientId = patient.Id;

Multiple patients

Use create_patients_batch / CreatePatientsBatch to register up to 500 patients in one POST /v1/patients/batch call. Pass a list of CreatePatientRequest objects; the response is a PatientBatchResult with successes and per-index errors; partial success is supported.

from olira import CreatePatientRequest, ExternalIdentifier

result = olira.create_patients_batch([
    CreatePatientRequest(
        first_name=row["first_name"],
        last_name=row["last_name"],
        email=row.get("email"),
        external_identifiers=[ExternalIdentifier(system="mrn", value=row["mrn"])],
    )
    for row in enrollment_rows
])
for item in result.items:
    # item.index → position in input list, item.id → Olira patient id
    ...
for err in result.errors:
    # err.index, err.code, err.message: handle or retry failed rows
    ...

var result = OliraModule.CreatePatientsBatch(
    enrollmentRows.Select(row => new CreatePatientRequest
    {
        FirstName = row.FirstName,
        LastName = row.LastName,
        Email = row.Email,
        ExternalIdentifiers =
        [
            new ExternalIdentifier { System = "mrn", Value = row.Mrn },
        ],
    }).ToList());
foreach (var item in result.Items)
{
    // item.Index → position in input list, item.Id → Olira patient id
}
foreach (var err in result.Errors)
{
    // err.Index, err.Code, err.Message: handle or retry failed rows
}

Build the request list from a comprehension, a CSV import, or any iterator. For a single registration you can still use create_patient / CreatePatient. Anchor rules and field shapes match CreatePatientRequest in the SDK reference.

Log data

Send structured logs with an OliraLogType and a payload that matches that type (see the log types catalog). Use the correct patient id for each log. log() is a tap: it enqueues and returns immediately, so you can emit from inside a request or workflow without waiting on Olira. It has no idempotency_key — if that path runs twice, you get two events.

from olira import OliraLogType

olira.log(
    log_type=OliraLogType.SYMPTOM_REPORT,
    patient_id=patient_id,
    payload={"instrument": "esas_r", "symptoms": [{"name": "pain", "score": 3}]},
)
olira.flush()

OliraModule.Log(
    logType: OliraLogType.SymptomReport,
    patientId: patientId,
    payload: new Dictionary<string, object?>
    {
        ["instrument"] = "esas_r",
        ["symptoms"] = new List<object?>
        {
            new Dictionary<string, object?> { ["name"] = "pain", ["score"] = 3 },
        },
    });
OliraModule.Flush();

log_batch() sends immediately and returns accepted / failed. Use it when you need the write confirmed, or when you might retry the same call — set idempotency_key to a stable id you own (your record id is a good choice). See Retries and idempotency.

from olira import LogSpec, OliraLogType

result = olira.log_batch([
    LogSpec(
        log_type=OliraLogType.SYMPTOM_REPORT,
        patient_id=patient_id,
        payload={"instrument": "esas_r", "symptoms": [{"name": "pain", "score": 3}]},
        idempotency_key="esas-r-2026-03-18-ada",
    ),
])

var result = OliraModule.LogBatch(
    [
        new LogSpec(
            logType: OliraLogType.SymptomReport,
            patientId: patientId,
            payload: new Dictionary<string, object?>
            {
                ["instrument"] = "esas_r",
                ["symptoms"] = new List<object?>
                {
                    new Dictionary<string, object?> { ["name"] = "pain", ["score"] = 3 },
                },
            },
            idempotencyKey: "esas-r-2026-03-18-ada"),
    ]);

Use log_fhir() when your source data is already FHIR R4. It is a confirmed write like log_batch — pass idempotency_key the same way if you might retry. Optional OliraTrace links a log to an object in your system (conversation id, questionnaire id, etc.) for provenance in observability and when reading state later.

Verify ingestion

When your organization has observability enabled, use Observability → Logs and Events in the Console, and Patient detail to confirm modules and views update as expected. See Console observability.

Get started

Send data

Read data

Outbound actions

Console

Logging from your codebase

Install tooling

Authenticate in your service

Initialize the SDK and create patients

Single patient

Multiple patients

Log data

Verify ingestion

​Install tooling

​Authenticate in your service

​Initialize the SDK and create patients

​Single patient

​Multiple patients

​Log data

​Verify ingestion

Install tooling

Authenticate in your service

Initialize the SDK and create patients

Single patient

Multiple patients

Log data

Verify ingestion