Resource ingestion

This feature is in beta. Behavior and availability may change as we expand support.

Use resource ingestion when you have clinical PDFs or related images (scans, screenshots, print-to-PDF notes) that should become structured logs in Olira. You label the target log type at upload time; Olira stores the binary, runs text extraction / OCR, then emits an event log that flows into patient state like any other submission. This path is for document binaries. For already-structured payloads, use live logging or historical JSONL backfill. For continuous sensor Parquet, use passive signal ingestion.

Supported materials

Kind	Content types
PDF	`application/pdf`
Images	`image/png`, `image/jpeg`, `image/jpg`, `image/webp`, `image/tiff`, `image/gif`

Max file size is 100 MB per document. You choose the clinical target — the platform does not infer log_type or document_type / note_type from the filename.

Target log types

`log_type`	Required labels	When to use
`unstructured_report`	`document_type`	Raw document blob for extraction (labs, imaging reports, discharge packets, etc.)
`clinical_note`	`note_type` + `source`	Provider-authored note that should land as a `clinical_note` log

document_type values (for unstructured_report): clinical_note, radiology_imaging, operative_procedure, cardiology_diagnostic, pathology_report, lab_report, genomic_report, discharge_summary, patient_intake, external_records_package. note_type values (for clinical_note): progress_note, history_and_physical, social_history, family_history, medical_history, surgical_history, psychosocial_history, financial_history, discharge_summary, consultation_note, other. Payload schemas: clinical note, unstructured report.

Processing modes

processing_mode decides how many event logs one file becomes.

Mode	`timestamp`	Emits	Use when
`single_document` (default)	required	one log for the whole file	the file is one clinical event at one date — a progress note, a lab report, a discharge summary
`segmented_notes`	must be omitted	one `clinical_note` per detected encounter	the file spans many encounters — a scanned paper folder, a longitudinal records package

Why `segmented_notes` exists

In single_document mode every fact extracted from a file inherits that file’s one timestamp. That is correct for a single note, and wrong for a document covering years: a scanned clinic folder spanning 2018→2025 would land every blood pressure, diagnosis, and prescription in it on one date, and patient state would read as though all of it happened at once. In segmented_notes mode the file is treated as a container, not an event. It carries no timestamp and produces no log of its own. Olira finds each dated encounter entry in the OCR text and emits one clinical_note per entry, timestamped from the date written in the document. Each note then runs extraction independently, so its vitals_measurement, medication, and condition children carry the right visit date. Requires log_type: clinical_note (with note_type + source, which apply to every emitted note).

Hints

Two optional fields make date inference safer. Both are hints, not guarantees, and both are only accepted in segmented_notes mode.

date_hints={"from": "2018-03", "to": "2025-01", "day_first": True}
layout_hints={"pages": [{"left": "identity card", "right": "clinical notes"}]}

date_hints bounds the document’s clinical span (YYYY, YYYY-MM, or a full ISO date) and says whether dates are written day-first. The span disambiguates two-digit years and rejects an implausible reading; day_first settles 03/04 between 3 April and March 4th.
layout_hints says what each page holds, in page order, so a printed identity card or a blank end-of-folder leaf is recognised rather than absorbed into a note.

Held segments

A detected segment is held — not emitted — when its date cannot be resolved, falls outside date_hints, or goes backwards relative to the previous entry, and when its text is empty or implausibly long. Held segments never become logs, and every one is listed on GET /v1/documents/{id} with a hold_reason, alongside segments_detected / segments_emitted / segments_held and unassigned_chars (non-whitespace characters that belonged to no segment and no classified region). A rising unassigned_chars is the signal that a split is dropping content.

Pipeline

Upload binary → commit → textize / OCR → [segment] → emit event log(s) → patient state / views

Upload — request a presigned URL, PUT the file bytes (with matching Content-Type), then commit.
Textize — for born-digital PDFs (Word→PDF, EHR print-to-PDF), Olira prefers the embedded text layer when quality checks pass (chars/page, letter ratio, nonempty pages).
Vision OCR — scanned PDFs, sparse text layers, and images fall back to vision OCR.
Segment — segmented_notes only: find each dated encounter entry and resolve its date.
Emit — Olira writes the event log(s) and continues through the normal graph / extraction path.

There is no human confirmation on the live document path. Commit starts OCR immediately.

Two ways to send resources

Live upload (single document)

Best for ongoing document arrival from your backend. Requires sdk:event-log.

from datetime import datetime, timezone
from olira import OliraClient

client = OliraClient(api_key="YOUR_API_KEY")

handle = client.upload_document(
    patient_id="8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
    path="progress-note.pdf",
    log_type="unstructured_report",
    document_type="clinical_note",
    timestamp=datetime(2026, 7, 15, 14, 30, tzinfo=timezone.utc),
    idempotency_key="emr-note-88421",
)
doc = handle.wait()  # or handle.poll()
print(doc.status, doc.event_log_id, doc.ocr_page_count)

using Olira;

using var client = new OliraClient(apiKey: "YOUR_API_KEY");

var handle = client.UploadDocument(
    patientId: "8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
    path: "progress-note.pdf",
    logType: DocumentLogType.UnstructuredReport,
    documentType: "clinical_note",
    timestamp: new DateTimeOffset(2026, 7, 15, 14, 30, 0, TimeSpan.Zero),
    idempotencyKey: "emr-note-88421");
var doc = handle.Wait();  // or handle.Poll()
Console.WriteLine($"{doc.Status} {doc.EventLogId} {doc.OcrPageCount}");

For a clinical-note target:

handle = client.upload_document(
    patient_id="8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
    path="h-and-p.pdf",
    log_type="clinical_note",
    note_type="history_and_physical",
    source="ehr_integration",
    timestamp=datetime(2026, 7, 15, 14, 30, tzinfo=timezone.utc),
    idempotency_key="emr-note-88422",
)

handle = client.UploadDocument(
    patientId: "8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
    path: "h-and-p.pdf",
    logType: DocumentLogType.ClinicalNote,
    noteType: "history_and_physical",
    source: "ehr_integration",
    timestamp: new DateTimeOffset(2026, 7, 15, 14, 30, 0, TimeSpan.Zero),
    idempotencyKey: "emr-note-88422");

For a scanned multi-visit folder — note there is no timestamp:

handle = client.upload_document(
    patient_id="8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
    path="paper-folder.pdf",
    log_type="clinical_note",
    processing_mode="segmented_notes",
    note_type="progress_note",
    source="ehr_import",
    date_hints={"from": "2018-03", "to": "2025-01", "day_first": True},
    layout_hints={"pages": [{"left": "identity card", "right": "clinical notes"}]},
    idempotency_key="c360-b2-001-folder",
)
doc = handle.wait()
print(doc.status, doc.segments_emitted, doc.segments_held, doc.event_log_ids)
for seg in doc.segments:
    print(seg.index, seg.timestamp, seg.status, seg.hold_reason)

Under the hood the SDK calls:

POST /v1/documents:upload-url
Presigned PUT of the binary
POST /v1/documents/{id}:commit
GET /v1/documents/{id} while you poll

Method reference: upload_document, get_document.

Historical package (bulk PDFs + logs)

Best for onboarding backfills that mix JSONL-style patient/log rows with PDF binaries. Requires sdk:historical-ingest.

from olira import OliraClient
from olira.models import IngestDocument, IngestRecord, IngestLogSpec

client = OliraClient(api_key="YOUR_API_KEY")

job = client.create_ingestion_job(
    records=[
        IngestRecord.log(
            IngestLogSpec(
                event_type="symptom_report",
                patient_id="MRN-104",
                timestamp="2026-03-01T09:00:00Z",
                payload={"instrument": "esas_r", "symptoms": [{"name": "fatigue", "score": 4}]},
            )
        ),
    ],
    documents=[
        IngestDocument(
            path="discharge-summary.pdf",
            patient_id="MRN-104",
            log_type="unstructured_report",
            document_type="discharge_summary",
            timestamp="2026-03-01T10:00:00Z",
            idempotency_key="MRN-104:doc:discharge-1",
        ),
    ],
    idempotency_key="onboarding-docs-2026-q1",
    require_confirmation=True,
)

The SDK allocates upload URLs (POST /v1/ingestion/jobs:begin), PUTs each PDF, builds a manifest.jsonl that includes type=document rows, then creates the historical job. After you confirm, OCR and document log materialization run inside the historical workflow before view backfill. See create_ingestion_job and Backfilling historical data for confirmation, cancel, and progress polling.

Document statuses

Status	Meaning
`pending_upload`	Upload URL issued; binary not yet verified
`uploaded`	Object landed (intermediate)
`ocr_running`	Textize / OCR in progress
`ocr_complete`	Text extracted; event log emit in progress (non-terminal)
`segmenting`	`segmented_notes`: splitting the text into dated encounters (non-terminal)
`log_emitted`	Single event log written (`event_log_id` set) — success
`logs_emitted`	`segmented_notes`: per-encounter logs written (`event_log_ids` set) — success
`ocr_failed`	OCR or emit failed (`error` may explain)
`segmentation_failed`	`segmented_notes`: the split itself failed (`error` may explain)

Terminal statuses: log_emitted, logs_emitted, ocr_failed, segmentation_failed. Individual segments being held is not a failure — a document with held segments still reaches logs_emitted. Check segments_held to see it.

What you need

API key with sdk:event-log (live upload) or sdk:historical-ingest (package jobs).
Patient already in your org (or created in the same historical package via patient rows).
A PDF or supported image file, plus the correct log_type labels.
A stable idempotency_key so retries do not create duplicate document resources. This is a separate key from the one on log_batch / log_fhir (log() has no key) — document uploads have their own idempotency scope.

After emit

Once status is log_emitted (or logs_emitted), treat the result like any other log: inspect it in Console observability, read it via state / log query APIs, and expect downstream extraction and view updates according to your org configuration. Re-using the same idempotency_key after a document already left pending_upload returns a conflict — pick a new key for a new file.

Get started

Send data

Read data

Outbound actions

Console

Resource ingestion

Supported materials

Target log types

Processing modes

Why `segmented_notes` exists

Hints

Held segments

Pipeline

Two ways to send resources

Live upload (single document)

Historical package (bulk PDFs + logs)

Document statuses

What you need

After emit

​Supported materials

​Target log types

​Processing modes

​Why segmented_notes exists

​Hints

​Held segments

​Pipeline

​Two ways to send resources

​Live upload (single document)

​Historical package (bulk PDFs + logs)

​Document statuses

​What you need

​After emit

Supported materials

Target log types

Processing modes

Why `segmented_notes` exists

Hints

Held segments

Pipeline

Two ways to send resources

Live upload (single document)

Historical package (bulk PDFs + logs)

Document statuses

What you need

After emit