Upload document

POST

documents:upload-url

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()

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();

POST /v1/documents:upload-url
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "patient_id": "8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
  "content_type": "application/pdf",
  "content_sha256": "<sha256 of file>",
  "size_bytes": 48210,
  "filename": "progress-note.pdf",
  "log_type": "unstructured_report",
  "document_type": "clinical_note",
  "timestamp": "2026-07-15T14:30:00+00:00",
  "idempotency_key": "emr-note-88421"
}

# Then PUT upload_url with Content-Type: application/pdf (no Authorization),
# then POST /v1/documents/{document_id}:commit

DocumentResource(
    document_id="doc-001",
    status="log_emitted",
    filename="progress-note.pdf",
    event_log_id="…",
    ocr_page_count=3,
)

{
  "error": true,
  "status_code": 401,
  "error_type": "authentication_error",
  "message": "Could not validate credentials",
  "details": [
    {
      "type": "authentication_error",
      "message": "Could not validate credentials"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 403,
  "error_type": "authorization_error",
  "message": "Insufficient OAuth scope for this endpoint",
  "details": [
    {
      "type": "authorization_error",
      "message": "Insufficient OAuth scope for this endpoint"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 404,
  "error_type": "not_found_error",
  "message": "Patient not found",
  "details": [
    {
      "type": "not_found_error",
      "message": "Patient not found"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 422,
  "error_type": "validation_error",
  "message": "Request validation failed (1 error)",
  "details": [
    {
      "type": "missing",
      "message": "Field required",
      "field": "patient_id",
      "location": ["body", "patient_id"],
      "input_value": null
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 429,
  "error_type": "server_error",
  "message": "Rate limit exceeded",
  "details": [
    {
      "type": "rate_limit",
      "message": "Too many requests; retry after backoff"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 500,
  "error_type": "internal_server_error",
  "message": "An internal server error occurred",
  "details": [
    {
      "type": "internal_server_error",
      "message": "An unexpected error occurred while processing your request"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

olira.upload_document(
    patient_id: str,
    path: str | Path,
    log_type: DocumentLogType | str,
    idempotency_key: str,
    timestamp: datetime | None = None,
    processing_mode: DocumentProcessingMode | str = "single_document",
    date_hints: dict | None = None,
    layout_hints: dict | None = None,
    document_type: str | None = None,
    note_type: str | None = None,
    source: Any | None = None,
    content_type: str | None = None,
    wait: bool = False,
    wait_timeout_s: float = 600.0,
) -> DocumentHandle

client.UploadDocument(
    string patientId,
    string | Path path,
    DocumentLogType | string logType,
    string idempotencyKey,
    DateTimeOffset? timestamp = null,
    DocumentProcessingMode | string processingMode = "single_document",
    dict? dateHints = null,
    dict? layoutHints = null,
    string? documentType = null,
    string? noteType = null,
    Any? source = null,
    string? contentType = null,
    bool wait = false,
    double waitTimeoutS = 600.0,
)  // -> DocumentHandle

Requires scope: sdk:event-log The SDK requests a presigned URL, PUTs the binary (with matching Content-Type), commits, and returns a DocumentHandle — call wait() or poll() until a terminal status. You choose log_type and labels; the platform does not infer them from the file. processing_mode=segmented_notes treats the file as a container spanning many encounters: omit timestamp and the platform emits one clinical_note per detected visit entry, each dated from the document’s own content. See the resource ingestion guide for supported formats, the textize/OCR pipeline, and held segments.

Parameters

str

required

Olira patient id that owns the document.

str | Path

required

Local filesystem path to a PDF or supported image (max 100 MB).

DocumentLogType | str

required

“unstructured_report” (requires document_type) or “clinical_note” (requires note_type + source).

str

required

Stable key for this document; reusing after leaving pending_upload returns 409.

datetime | None

Clinical timestamp for the emitted event log (timezone-aware preferred). Required for processing_mode=single_document; must be omitted for segmented_notes, where each note is dated from the document’s content.

DocumentProcessingMode | str

default:"\"single_document\""

single_document emits one log for the whole file at the timestamp you supply. segmented_notes emits one clinical_note per detected encounter, each dated from the OCR text — requires log_type=clinical_note and no timestamp.

dict | None

segmented_notes only. Bounds and disambiguates inferred dates: {“from”: “2018-03”, “to”: “2025-01”, “day_first”: True}. from/to accept YYYY, YYYY-MM, or a full ISO date.

dict | None

segmented_notes only. What each page holds, in page order: {“pages”: [{“left”: “identity card”, “right”: “clinical notes”}]}. Used to recognise non-note leaves.

str | None

Required for unstructured_report. Catalog enum (e.g. clinical_note, lab_report, discharge_summary).

str | None

Required for clinical_note. Catalog enum (e.g. progress_note, history_and_physical).

Any | None

Required for clinical_note (e.g. ehr_integration, manual_entry, or structured Source).

str | None

MIME type override; defaults from filename (application/pdf, image/png, …).

bool

default:"False"

When True, block until a terminal status before returning the handle.

float

default:"600.0"

Timeout for wait=True / handle.wait().

Returns

DocumentHandle — Poll/wait handle; .document is the current DocumentResource snapshot.

str

Document resource id.

DocumentStatus

str | None

Emitted event log id when status is log_emitted (single_document).

list[str]

Per-encounter event log ids when status is logs_emitted (segmented_notes).

list[DocumentSegment]

Detected encounters: index, page range, resolved timestamp, status (emitted | held) and hold_reason.

int | None

Segments that became logs. See also segments_detected / segments_held.

int | None

Non-whitespace characters in no segment and no classified region — a dropped-content signal.

int | None

Pages processed by OCR when available.

str | None

Failure detail when status is ocr_failed or segmentation_failed.

Guide: /send-data/resource-ingestion.

On the presigned PUT, send Content-Type matching the upload-url request; omit the SDK Authorization header.

There is no human confirmation on this path — commit starts OCR immediately.

Raises

Exception	When
`ValidationError`	File missing/empty; required document_type / note_type+source omitted for the chosen log_type; timestamp missing under single_document or supplied under segmented_notes.
`AuthError`	HTTP 401 or 403 — invalid API key or insufficient OAuth scope for this endpoint.
`ServerError`	HTTP 409 (e.g. conflicting external identifier) or repeated 5xx after retries; includes status_code when applicable.
`RateLimitError`	HTTP 429 — rate limited; check retry_after (seconds).
`NetworkError`	Connection timeout, DNS failure, or read error after retries.

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()

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();

POST /v1/documents:upload-url
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "patient_id": "8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
  "content_type": "application/pdf",
  "content_sha256": "<sha256 of file>",
  "size_bytes": 48210,
  "filename": "progress-note.pdf",
  "log_type": "unstructured_report",
  "document_type": "clinical_note",
  "timestamp": "2026-07-15T14:30:00+00:00",
  "idempotency_key": "emr-note-88421"
}

# Then PUT upload_url with Content-Type: application/pdf (no Authorization),
# then POST /v1/documents/{document_id}:commit

DocumentResource(
    document_id="doc-001",
    status="log_emitted",
    filename="progress-note.pdf",
    event_log_id="…",
    ocr_page_count=3,
)

{
  "error": true,
  "status_code": 401,
  "error_type": "authentication_error",
  "message": "Could not validate credentials",
  "details": [
    {
      "type": "authentication_error",
      "message": "Could not validate credentials"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 403,
  "error_type": "authorization_error",
  "message": "Insufficient OAuth scope for this endpoint",
  "details": [
    {
      "type": "authorization_error",
      "message": "Insufficient OAuth scope for this endpoint"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 404,
  "error_type": "not_found_error",
  "message": "Patient not found",
  "details": [
    {
      "type": "not_found_error",
      "message": "Patient not found"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 422,
  "error_type": "validation_error",
  "message": "Request validation failed (1 error)",
  "details": [
    {
      "type": "missing",
      "message": "Field required",
      "field": "patient_id",
      "location": ["body", "patient_id"],
      "input_value": null
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 429,
  "error_type": "server_error",
  "message": "Rate limit exceeded",
  "details": [
    {
      "type": "rate_limit",
      "message": "Too many requests; retry after backoff"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 500,
  "error_type": "internal_server_error",
  "message": "An internal server error occurred",
  "details": [
    {
      "type": "internal_server_error",
      "message": "An unexpected error occurred while processing your request"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

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()

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();

POST /v1/documents:upload-url
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "patient_id": "8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
  "content_type": "application/pdf",
  "content_sha256": "<sha256 of file>",
  "size_bytes": 48210,
  "filename": "progress-note.pdf",
  "log_type": "unstructured_report",
  "document_type": "clinical_note",
  "timestamp": "2026-07-15T14:30:00+00:00",
  "idempotency_key": "emr-note-88421"
}

# Then PUT upload_url with Content-Type: application/pdf (no Authorization),
# then POST /v1/documents/{document_id}:commit

DocumentResource(
    document_id="doc-001",
    status="log_emitted",
    filename="progress-note.pdf",
    event_log_id="…",
    ocr_page_count=3,
)

{
  "error": true,
  "status_code": 401,
  "error_type": "authentication_error",
  "message": "Could not validate credentials",
  "details": [
    {
      "type": "authentication_error",
      "message": "Could not validate credentials"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 403,
  "error_type": "authorization_error",
  "message": "Insufficient OAuth scope for this endpoint",
  "details": [
    {
      "type": "authorization_error",
      "message": "Insufficient OAuth scope for this endpoint"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 404,
  "error_type": "not_found_error",
  "message": "Patient not found",
  "details": [
    {
      "type": "not_found_error",
      "message": "Patient not found"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 422,
  "error_type": "validation_error",
  "message": "Request validation failed (1 error)",
  "details": [
    {
      "type": "missing",
      "message": "Field required",
      "field": "patient_id",
      "location": ["body", "patient_id"],
      "input_value": null
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 429,
  "error_type": "server_error",
  "message": "Rate limit exceeded",
  "details": [
    {
      "type": "rate_limit",
      "message": "Too many requests; retry after backoff"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

{
  "error": true,
  "status_code": 500,
  "error_type": "internal_server_error",
  "message": "An internal server error occurred",
  "details": [
    {
      "type": "internal_server_error",
      "message": "An unexpected error occurred while processing your request"
    }
  ],
  "timestamp": "2026-05-06T12:00:00+00:00"
}

​Parameters

​Returns

​Raises

Parameters

Returns

Raises