SDK - Olira

The Olira SDKs are the supported way to send health logs, manage patients, run historical data ingestion jobs, upload passive sensor Parquet, mint patient tokens, read patient state, run batch exports, and manage outbound-action destinations from your backend. Method-by-method reference with parameters, responses, REST equivalents, and Python / C# examples lives under the category groups in the sidebar.

Language	Package	Target
Python	`olira` on PyPI	Python 3.11+
.NET / C#	`Olira` on NuGet	.NET 8

For bulk backfill workflows (JSONL upload, job confirmation, replay), see the historical backfill guide. For clinical PDFs and related images, see resource ingestion. For multi-Hz accelerometer / gyroscope / GPS Parquet, see passive signal ingestion. For webhooks and email notifications when something happens on the platform, see outbound actions.

Installation

pip install olira
# Optional: serialize records= to Parquet for send_signals
pip install olira[signals]

dotnet add package Olira

Authentication

Use an API key with the OAuth scopes required for each operation (see Authentication). Set OLIRA_API_KEY or pass the key explicitly.

Scope	Used for
`sdk:event-log`	Log events, FHIR resource ingest, document upload, passive signals
`api:manage-patients`	Patient CRUD, batch create, and cohort management
`sdk:patient-token`	Mint patient tokens
`sdk:state-read`	Stable data, event modules, views, logs, events, memories, log query builder, batch exports
`sdk:historical-ingest`	Historical ingestion jobs
`api:org-config`	Org schema management; confidence scoring config (org / view / block)
`sdk:integrations`	Integration management — catalog, connect/disconnect, data-point subscriptions, sync status (control-plane only)
`sdk:actions`	Outbound-action destinations, signing secrets, and delivery history
`sdk:integration-write`	Honors the `write_back` flag on log APIs for EHR write-back requests
`api:manage-projects`	Project management — requires an org-wide key
`mcp:patient-state`	Query patient state via the MCP Patient State server

Base URL

The default HTTP origin is https://app-api.prod.olira.ai/app-api. Override the base URL on init / the client constructor only when your integration uses a custom gateway or another non-default endpoint.

Initialize the client

Most examples use a process-wide singleton. Prefer an explicit client when you need multiple keys, DI, or tests.

import olira

olira.init(api_key="YOUR_API_KEY")
# … olira.log(...), olira.create_patient(...), etc.
olira.flush()  # optional: block until queued logs are sent

using Olira;

OliraModule.Init(apiKey: "YOUR_API_KEY");
// … OliraModule.Log(...), OliraModule.CreatePatient(...), etc.
OliraModule.Flush();  // optional: block until queued logs are sent

Explicit client

from olira import OliraClient

client = OliraClient(api_key="YOUR_API_KEY")
try:
    client.log(log_type=..., patient_id="...", payload={})
    patient = client.create_patient(email="a@b.com")
finally:
    client.close()

using Olira;

using var client = new OliraClient(apiKey: "YOUR_API_KEY");
client.Log(logType: OliraLogType.SymptomReport, patientId: "...", payload: new Dictionary<string, object?>());
var patient = client.CreatePatient(email: "a@b.com");

Python
C#

`olira.init(...)`

Parameter	Type	Default	Description
`api_key`	`str \| None`	env `OLIRA_API_KEY`	Secret key; required after env fallback
`service_name`	`str \| None`	`None`	Included in log context
`base_url`	`str`	`https://app-api.prod.olira.ai/app-api`	HTTP origin; override when required
`batch_size`	`int`	`50`	Background batch size
`flush_interval`	`float`	`1.5`	Seconds between background flushes
`max_queue_size`	`int`	`10000`	Max queued events
`timeout`	`float`	`5.0`	HTTP timeout (seconds)
`max_retries`	`int`	`3`	Retries for transient failures
`on_error`	`str \| Callable`	`"drop"`	Queue behavior on send failure (`"drop"` or callback)
`async_flush`	`bool`	`True`	When `True`, background worker batches `log()`; when `False`, each batch sends synchronously

Raises OliraError if no API key is available.

`olira.flush()`

Blocks until queued logs are flushed (or fails after worker policy). Raises OliraError if init() was never called.

`AsyncOliraClient`

Async variant with identical method names, prefixed with async/await:

from olira import AsyncOliraClient, OliraLogType

async def main():
    async with AsyncOliraClient(api_key="YOUR_API_KEY") as client:
        await client.log(
            log_type=OliraLogType.SYMPTOM_REPORT,
            patient_id="...",
            payload={},
        )
        await client.flush()

# asyncio.run(main())

Differences from sync: no on_error / async_flush on the constructor; you must enter async with (or equivalent) before calling API methods, otherwise ValidationError is raised. Use await client.aclose() if not using a context manager.

`OliraModule.Init(...)`

Parameter	Type	Default	Description
`apiKey`	`string?`	env `OLIRA_API_KEY`	Secret key; required after env fallback
`environment`	`OliraEnv`	`Production`	Event-routing environment
`serviceName`	`string?`	`null`	Included in log context
`project`	`string?`	env `OLIRA_PROJECT`	Project id/slug (`X-Olira-Project`)
`baseUrl`	`string`	`https://app-api.prod.olira.ai/app-api`	HTTP origin; override when required
`batchSize`	`int`	`50`	Background batch size
`flushInterval`	`double`	`1.5`	Seconds between background flushes
`maxQueueSize`	`int`	`10000`	Max queued events
`timeout`	`double`	`5.0`	HTTP timeout (seconds)
`maxRetries`	`int`	`3`	Retries for transient failures
`onError`	`object?`	`"drop"`	`"drop"`, `"raise"`, or an error callback
`asyncFlush`	`bool`	`true`	When `true`, background worker batches `Log()`

Throws OliraError if no API key is available.

`OliraModule.Flush()`

Blocks until queued logs are flushed. Throws OliraError if Init() was never called.

Async methods

OliraClient exposes *Async counterparts (CreatePatientAsync, LogAsync, FlushAsync, …) that accept an optional CancellationToken. Prefer await using var client = new OliraClient(...) when you need async I/O.

Error hierarchy

Exception names match across SDKs:

Exception	Meaning
`OliraError`	Base class; configuration errors (e.g. missing init)
`AuthError`	HTTP 401 / 403
`ValidationError`	HTTP 400 / 404 / 422 or client-side validation (e.g. PII in `patient_id`, payload too large)
`RateLimitError`	HTTP 429; attribute `retry_after` / `RetryAfter` (seconds)
`ServerError`	HTTP 409 or 5xx after retries; attribute `status_code` / `StatusCode` when applicable
`NetworkError`	Connection / timeout after retries

Models and helpers (overview)

Full field lists for request/response types appear next to each method in the sidebar reference. Naming is snake_case in Python and PascalCase in C# (patient_id ↔ PatientId, OliraLogType.SYMPTOM_REPORT ↔ OliraLogType.SymptomReport).

Symbol	Role
`OliraLogType`	Catalog log types; see the log types catalog for payloads
`OliraTrace`	`object_type` / `ObjectType` + `object_id` / `ObjectId` for correlating logs
`LogSpec`	Row for batch log APIs (`log_type`, `patient_id`, `payload`, `trace`, `timestamp`, `idempotency_key`, `metadata`)
Patient request/response models	`ExternalIdentifier`, `CreatePatientRequest`, `Patient`, `PatientListResult`, `PatientBatchResult`, `PatientToken`
State-read models	`StableDataResult`, `EventStateModuleSummary`, `ViewMeta`, `ViewBlocksListResult`, `ViewResult`, `ViewBlockResult`, `LogsResult`, `EventsResult`, `MemoriesResult`, etc.
`ConfidenceScoringResult`	Org / view / block confidence scoring config response (`scope`, optional `summary_type` / `block_id`, `confidence_scoring`).
`LogQueryResult`	Result of the log query builder. Iterable, indexable; fields include `count` / `Count`, `rows` / `Rows`, `patient_id` / `PatientId`.
`LogQuery`	Fluent builder from `logs(patient_id)` / `Logs(patientId)` and `population_logs` / `PopulationLogs`. Chain filters then call a terminal (`.execute()` / `.Execute()`, `.count()` / `.Count()`, …).
`F(field)`	Expression helper for `.or_()` / `.Or()` sub-conditions
Ingestion models	`IngestRecord`, `IngestLogSpec`, `IngestionJob`, `IngestionJobListResult`, `IngestionErrorSummary`

Examples

Runnable scripts ship with each SDK:

Topic	Python	.NET
Quickstart	`00_quickstart.py`	`00_Quickstart`
Patient management	`01_patient_management.py`	`01_PatientManagement`
Event logging	`02_event_logging.py`	`02_EventLogging`
FHIR ingestion	`03_fhir_ingestion.py`	`03_FhirIngestion`
Historical ingestion	`04_historical_ingestion.py`	`04_HistoricalIngestion`
Read patient state	`06_read_patient_state.py`	`06_ReadPatientState`
Patient token	`07_patient_token.py`	`07_PatientToken`
Passive signals	`11_signals.py`	`11_Signals`

Resource ingestion

Upload clinical PDFs and related images with upload_document / UploadDocument (scope sdk:event-log). Olira runs text extraction / OCR and emits an unstructured_report or clinical_note log. Method pages live under Documents in the sidebar. For bulk packages mixed with historical rows, pass documents to create_ingestion_job / CreateIngestionJob (scope sdk:historical-ingest). Guide: Resource ingestion.

Passive signals

Upload continuous sensor Parquet with send_signals / SendSignals (scope sdk:event-log). Supported today: accelerometer, gyroscope, GPS — more sensors will follow. Method pages live under Signals in the sidebar. Guide: Passive signal ingestion.

FHIR ingestion

Use log_fhir / LogFhir (scope sdk:event-log, POST /v1/fhir/resource) to submit a single FHIR R4 resource. Olira maps it through the same FHIR absorber used by Epic/Cerner integrations. Full parameters, examples, and error cases are under Logs → Log FHIR resource in the sidebar. Single-resource limit: Each call accepts one FHIR resource. Linked resources in the same payload are not resolved together. Use historical ingestion or an EHR integration for multi-resource imports.

Cohorts

Cohorts are named patient groups scoped to your organization. Use them to assign summary types to a defined set of patients without touching individual records. Method-by-method reference lives under Cohorts in the sidebar; all methods require the api:manage-patients scope.

Projects

A project is a self-contained, isolated workspace within your organization: its own patients, event logs, patient state, views, cohorts, and platform configuration (see Projects). Every organization has exactly one default project; data written without a selected project lands there when using an org-wide key. To operate inside a project (create patients, send logs, read state), select it with project= / project: (id or slug) on init / the client rather than through the management methods. Under the hood this is sent as the X-Olira-Project header. create_project / CreateProject starts a project completely empty. duplicate_project / DuplicateProject copies only configuration, never patients, logs, or patient state. Method-by-method reference lives under Projects in the sidebar; all methods require the api:manage-projects scope and an org-wide key.

Schemas

Register your own event subtypes (e.g. myorg_widget_reading) and their translation into Olira’s platform catalog, self-service. Registering always lands as a pending request — Olira reviews and materializes the real schema + mapping before it can be activated. Method-by-method reference lives under Schemas in the sidebar; all methods require the api:org-config scope.

Confidence scoring

Configure how view blocks are scored for coverage, freshness, certainty, consistency, and evidence density — at the org default, view template, or block level (resolved org → view → block → platform built-ins). Method pages live under Confidence scoring in the sidebar (api:org-config). Prefer scorers[] (per builtin id such as builtin.freshness) plus top-level weights for the overall mix. Helpers get/set_view_scorer_params and set_view_confidence_weights patch one scorer or weights without rewriting the full config. See also Views & templates and View configuration.

Version

Python: import __version__ from olira, or check PyPI.
.NET: see the package version on NuGet, or the assembly informational version.

​Installation

​Authentication

​Base URL

​Initialize the client

​Explicit client

​olira.init(...)

​olira.flush()

​AsyncOliraClient

​OliraModule.Init(...)

​OliraModule.Flush()

​Async methods

​Error hierarchy

​Models and helpers (overview)

​Examples

​Resource ingestion

​Passive signals

​FHIR ingestion

​Cohorts

​Projects

​Schemas

​Confidence scoring

​Version