Skip to contentSkip to content

API reference ​

Explore API operations, request parameters, response formats, and data schemas. This reference is generated from the OpenAPI contract.

The public API is not yet available for integration. Requests cannot be sent from this page.

Base URLhttps://lissa.health/api/v1
Download OpenAPI
API operations

Health

GET/health

Anonymous public gateway liveness

Minimal anonymous liveness of the public gateway only. It does NOT confirm clinical-engine health, queue depth, balances or full compute readiness, and exposes no dependency details. No authentication.

No authenticationdraft
Parameters, authentication and responses
Responses
StatusContent typeResponseContract description
200application/jsonobjectGateway is alive.
503application/problem+jsonProblem503 — billing/admission/engine temporarily unavailable or same-key file intake is still in progress. codes: admission_unavailable, billing_unavailable, engine_unavailable, idempotency_in_progress. For idempotency_in_progress, Retry-After is present and the client safely retries the same key. Retry compute requests with the same `idempotency_key` in the request body; compute is not started when billing/DB is unavailable (fail-closed). Retry-After present.
API operations

Files

POST/files

Create an immutable file snapshot (binary upload or remote URL intake)

Accepts either multipart/form-data with one binary file part and an optional JSON request metadata part, or application/json with a remote HTTPS source. Put idempotency_key in the JSON body or multipart request part; it is required for remote URL intake and optional for binary upload. Repeating the same key and input returns the same immutable file ID; changing the input with the same key returns 409 idempotency_conflict. A retry while intake is in progress returns 503 idempotency_in_progress with Retry-After. The key is scoped to the authenticated account and operation. Remote URL intake is limited to HTTPS and protected against requests to private or link-local addresses. File type is determined from the uploaded content. Base64 and chunked upload are not supported.

Bearer token · Required scopes: files:writedraftIdempotency-Key required for some request variants
Parameters, authentication and responses
Request
Responses
StatusContent typeResponseContract description
201application/jsonFileImmutable file snapshot created or replayed. Both first creation and replay return 201 with the same immutable file ID; Location identifies `/v1/files/{file_id}`. Idempotency-Replayed is true on replay; initial response may be false or absent.
400application/problem+jsonProblem400 — malformed request or missing/invalid idempotency_key (required for URL intake and compute operations; optional for binary file upload). code: invalid_request.
401application/problem+jsonProblem401 — invalid/expired/revoked key. code: invalid_key.
403application/problem+jsonProblem403 — the key lacks a required scope for its own resource. code: insufficient_scope.
409application/problem+jsonProblem409 — changed idempotency fingerprint, resource not ready/in use, or terminal cancel. codes: idempotency_conflict, result_not_ready, job_not_completed, job_already_terminal, job_not_terminal, file_in_use. A transient same-key intake already in progress uses 503 idempotency_in_progress with Retry-After, not an ambiguous conflict.
413application/problem+jsonProblem413 — byte limit exceeded. code: payload_too_large.
415application/problem+jsonProblem415 — unsupported media type (allowlist is explicit; probe-based). code: unsupported_media_type.
422application/problem+jsonProblem422 — schema/page/duration/context validation failed; request well-formed but not acceptable. code: validation_failed.
429application/problem+jsonProblem429 — rate/concurrency/quota limit. code: rate_limit_exceeded. Retry-After present.
500application/problem+jsonProblem500 — internal error; a commit may still have happened. code: internal_error. Retry only with the same `idempotency_key` in the request body.
503application/problem+jsonProblem503 — billing/admission/engine temporarily unavailable or same-key file intake is still in progress. codes: admission_unavailable, billing_unavailable, engine_unavailable, idempotency_in_progress. For idempotency_in_progress, Retry-After is present and the client safely retries the same key. Retry compute requests with the same `idempotency_key` in the request body; compute is not started when billing/DB is unavailable (fail-closed). Retry-After present.
504application/problem+jsonProblem504 — intake/transport timeout; a commit may still have happened. code: intake_timeout. Retry only with the same `idempotency_key` in the request body.
Idempotency-Key policy

`idempotency_key` in the request body is required for JSON URL intake and optional for binary upload. Namespace: authenticated account + environment + createFile + key. Fingerprint binds the URL or uploaded-bytes digest + canonical metadata + content type; excludes multipart boundary and key. Same key/input replays the same immutable file ID; changed input is 409 idempotency_conflict. In-flight retry is 503 idempotency_in_progress with Retry-After; retry with the same key.

GET/files/{file_id}

Get file metadata/status

Returns metadata and lifecycle status (`ready|rejected|deleted|expired`), media type, actual bytes and retention. A foreign or non-existent id resolves to 404.

Bearer token · Required scopes: files:readdraft
Parameters, authentication and responses
Parameter
ParameterLocationTypeRequiredContract description
file_idpathstringRequired—
Responses
StatusContent typeResponseContract description
200application/jsonFileFile metadata.
401application/problem+jsonProblem401 — invalid/expired/revoked key. code: invalid_key.
403application/problem+jsonProblem403 — the key lacks a required scope for its own resource. code: insufficient_scope.
404application/problem+jsonProblem404 — not found or foreign resource (also a purged tombstone). An opaque id does not replace authorization. code: resource_not_found.
410application/problem+jsonProblem410 — payload expired/deleted. codes: result_expired, result_deleted.
429application/problem+jsonProblem429 — rate/concurrency/quota limit. code: rate_limit_exceeded. Retry-After present.
503application/problem+jsonProblem503 — billing/admission/engine temporarily unavailable or same-key file intake is still in progress. codes: admission_unavailable, billing_unavailable, engine_unavailable, idempotency_in_progress. For idempotency_in_progress, Retry-After is present and the client safely retries the same key. Retry compute requests with the same `idempotency_key` in the request body; compute is not started when billing/DB is unavailable (fail-closed). Retry-After present.

DELETE/files/{file_id}

Delete a file

Returns 204. If active jobs still reference the file, returns 409 `file_in_use` — cancel/wait for terminal first.

Bearer token · Required scopes: files:writedraft
Parameters, authentication and responses
Parameter
ParameterLocationTypeRequiredContract description
file_idpathstringRequired—
Responses
StatusContent typeResponseContract description
204——File deleted (idempotent for repeated deletes).
401application/problem+jsonProblem401 — invalid/expired/revoked key. code: invalid_key.
403application/problem+jsonProblem403 — the key lacks a required scope for its own resource. code: insufficient_scope.
404application/problem+jsonProblem404 — not found or foreign resource (also a purged tombstone). An opaque id does not replace authorization. code: resource_not_found.
409application/problem+jsonProblem409 — changed idempotency fingerprint, resource not ready/in use, or terminal cancel. codes: idempotency_conflict, result_not_ready, job_not_completed, job_already_terminal, job_not_terminal, file_in_use. A transient same-key intake already in progress uses 503 idempotency_in_progress with Retry-After, not an ambiguous conflict.
429application/problem+jsonProblem429 — rate/concurrency/quota limit. code: rate_limit_exceeded. Retry-After present.
503application/problem+jsonProblem503 — billing/admission/engine temporarily unavailable or same-key file intake is still in progress. codes: admission_unavailable, billing_unavailable, engine_unavailable, idempotency_in_progress. For idempotency_in_progress, Retry-After is present and the client safely retries the same key. Retry compute requests with the same `idempotency_key` in the request body; compute is not started when billing/DB is unavailable (fail-closed). Retry-After present.
API operations

Documents

POST/documents

Submit a document (durable paid operation)

Submit one PDF, scan, or image for structured extraction. The service selects how to read the document. Choose application/json with an existing file_id or HTTPS url, or upload the binary document and processing options together in one multipart/form-data request (file part plus JSON request part). idempotency_key is required in the request body. Set wait_seconds from 1 to 10 to wait for a completed result; if processing takes longer, the response contains the accepted job. The default is 0, which returns the job immediately. Requested features return their typed object; unrequested features are absent. classification controls whether document_info.detected_type may be returned; document_type_hint is only a hint. This service returns extracted information and is not a medical diagnosis.

Bearer token · Required scopes: documents:process, files:readdraftIdempotency-Key required
Parameters, authentication and responses
Request
Responses
StatusContent typeResponseContract description
200application/jsonDocumentResultOperation completed within wait_seconds; identical schema to GET /jobs/{job_id}/result.
202application/jsonJobThe job has been durably accepted. Returned immediately when wait_seconds is 0 or when processing does not finish within the requested wait.
400application/problem+jsonProblem400 — malformed request or missing/invalid idempotency_key (required for URL intake and compute operations; optional for binary file upload). code: invalid_request.
401application/problem+jsonProblem401 — invalid/expired/revoked key. code: invalid_key.
402application/problem+jsonProblem402 — insufficient balance or spend cap exceeded; the computation is not accepted. codes: insufficient_balance, spend_cap_exceeded.
403application/problem+jsonProblem403 — the key lacks a required scope for its own resource. code: insufficient_scope.
404application/problem+jsonProblem404 — not found or foreign resource (also a purged tombstone). An opaque id does not replace authorization. code: resource_not_found.
409application/problem+jsonProblem409 — changed idempotency fingerprint, resource not ready/in use, or terminal cancel. codes: idempotency_conflict, result_not_ready, job_not_completed, job_already_terminal, job_not_terminal, file_in_use. A transient same-key intake already in progress uses 503 idempotency_in_progress with Retry-After, not an ambiguous conflict.
413application/problem+jsonProblem413 — byte limit exceeded. code: payload_too_large.
415application/problem+jsonProblem415 — unsupported media type (allowlist is explicit; probe-based). code: unsupported_media_type.
422application/problem+jsonProblem422 — schema/page/duration/context validation failed; request well-formed but not acceptable. code: validation_failed.
429application/problem+jsonProblem429 — rate/concurrency/quota limit. code: rate_limit_exceeded. Retry-After present.
500application/problem+jsonProblem500 — internal error; a commit may still have happened. code: internal_error. Retry only with the same `idempotency_key` in the request body.
503application/problem+jsonProblem503 — billing/admission/engine temporarily unavailable or same-key file intake is still in progress. codes: admission_unavailable, billing_unavailable, engine_unavailable, idempotency_in_progress. For idempotency_in_progress, Retry-After is present and the client safely retries the same key. Retry compute requests with the same `idempotency_key` in the request body; compute is not started when billing/DB is unavailable (fail-closed). Retry-After present.
504application/problem+jsonProblem504 — intake/transport timeout; a commit may still have happened. code: intake_timeout. Retry only with the same `idempotency_key` in the request body.
Additional scopes
  • source is a remote urlfiles:write
  • the request is multipart/form-data with a binary file part (new upload)files:write
API operations

Transcription

POST/transcriptions

Submit an audio transcription (durable paid operation)

Submit one audio file for transcription. Choose application/json with an existing file_id or HTTPS url, or upload the audio and transcription options together in one multipart/form-data request (file part plus JSON request part). idempotency_key is required in the request body. Set wait_seconds from 1 to 10 to wait for a completed result; if processing takes longer, the response contains the accepted job. The default is 0, which returns the job immediately. Results include recognized text and timed segments; speaker labels distinguish voices and do not identify people or clinical roles.

Bearer token · Required scopes: transcriptions:create, files:readdraftIdempotency-Key required
Parameters, authentication and responses
Request
Responses
StatusContent typeResponseContract description
200application/jsonTranscriptionResultOperation completed within wait_seconds; same schema as GET /jobs/{job_id}/result.
202application/jsonJobThe job has been durably accepted. Returned immediately when wait_seconds is 0 or when processing does not finish within the requested wait.
400application/problem+jsonProblem400 — malformed request or missing/invalid idempotency_key (required for URL intake and compute operations; optional for binary file upload). code: invalid_request.
401application/problem+jsonProblem401 — invalid/expired/revoked key. code: invalid_key.
402application/problem+jsonProblem402 — insufficient balance or spend cap exceeded; the computation is not accepted. codes: insufficient_balance, spend_cap_exceeded.
403application/problem+jsonProblem403 — the key lacks a required scope for its own resource. code: insufficient_scope.
404application/problem+jsonProblem404 — not found or foreign resource (also a purged tombstone). An opaque id does not replace authorization. code: resource_not_found.
409application/problem+jsonProblem409 — changed idempotency fingerprint, resource not ready/in use, or terminal cancel. codes: idempotency_conflict, result_not_ready, job_not_completed, job_already_terminal, job_not_terminal, file_in_use. A transient same-key intake already in progress uses 503 idempotency_in_progress with Retry-After, not an ambiguous conflict.
413application/problem+jsonProblem413 — byte limit exceeded. code: payload_too_large.
415application/problem+jsonProblem415 — unsupported media type (allowlist is explicit; probe-based). code: unsupported_media_type.
422application/problem+jsonProblem422 — schema/page/duration/context validation failed; request well-formed but not acceptable. code: validation_failed.
429application/problem+jsonProblem429 — rate/concurrency/quota limit. code: rate_limit_exceeded. Retry-After present.
500application/problem+jsonProblem500 — internal error; a commit may still have happened. code: internal_error. Retry only with the same `idempotency_key` in the request body.
503application/problem+jsonProblem503 — billing/admission/engine temporarily unavailable or same-key file intake is still in progress. codes: admission_unavailable, billing_unavailable, engine_unavailable, idempotency_in_progress. For idempotency_in_progress, Retry-After is present and the client safely retries the same key. Retry compute requests with the same `idempotency_key` in the request body; compute is not started when billing/DB is unavailable (fail-closed). Retry-After present.
504application/problem+jsonProblem504 — intake/transport timeout; a commit may still have happened. code: intake_timeout. Retry only with the same `idempotency_key` in the request body.
Additional scopes
  • source is a remote urlfiles:write
  • the request is multipart/form-data with a binary file part (new upload)files:write
API operations

Jobs

GET/jobs/{job_id}

Get job status/metadata

Returns metadata/status, usage, safe error and result URL WITHOUT an embedded medical payload. A failed job still returns 200 because the status query succeeded. Execution status is exactly `queued|processing|cancel_requested|completed|failed|cancelled`; `result_availability` is a separate axis. Progress/ETA are advisory and nullable. A purged operational tombstone resolves to 404.

Bearer token · Required scopes: jobs:readdraft
Parameters, authentication and responses
Parameter
ParameterLocationTypeRequiredContract description
job_idpathstringRequired—
Responses
StatusContent typeResponseContract description
200application/jsonJobJob metadata/status.
401application/problem+jsonProblem401 — invalid/expired/revoked key. code: invalid_key.
403application/problem+jsonProblem403 — the key lacks a required scope for its own resource. code: insufficient_scope.
404application/problem+jsonProblem404 — not found or foreign resource (also a purged tombstone). An opaque id does not replace authorization. code: resource_not_found.
429application/problem+jsonProblem429 — rate/concurrency/quota limit. code: rate_limit_exceeded. Retry-After present.
503application/problem+jsonProblem503 — billing/admission/engine temporarily unavailable or same-key file intake is still in progress. codes: admission_unavailable, billing_unavailable, engine_unavailable, idempotency_in_progress. For idempotency_in_progress, Retry-After is present and the client safely retries the same key. Retry compute requests with the same `idempotency_key` in the request body; compute is not started when billing/DB is unavailable (fail-closed). Retry-After present.

GET/jobs/{job_id}/result

Get the typed final result

Returns the final product payload; the same result schema as a short sync response. `type` discriminates (`document|transcription`). 200 only when completed and the payload is available; 409 `result_not_ready` for an active job and `job_not_completed` for failed/cancelled; 410 `result_expired|result_deleted` after purge. The product scope is determined by the job type. A failed/cancelled job never exposes a partial payload.

Bearer token · Required scopes: jobs:readdraft
Parameters, authentication and responses
Parameter
ParameterLocationTypeRequiredContract description
job_idpathstringRequired—
Responses
StatusContent typeResponseContract description
200application/jsonJobResultAvailable final result.
401application/problem+jsonProblem401 — invalid/expired/revoked key. code: invalid_key.
403application/problem+jsonProblem403 — the key lacks a required scope for its own resource. code: insufficient_scope.
404application/problem+jsonProblem404 — not found or foreign resource (also a purged tombstone). An opaque id does not replace authorization. code: resource_not_found.
409application/problem+jsonProblem409 — changed idempotency fingerprint, resource not ready/in use, or terminal cancel. codes: idempotency_conflict, result_not_ready, job_not_completed, job_already_terminal, job_not_terminal, file_in_use. A transient same-key intake already in progress uses 503 idempotency_in_progress with Retry-After, not an ambiguous conflict.
410application/problem+jsonProblem410 — payload expired/deleted. codes: result_expired, result_deleted.
429application/problem+jsonProblem429 — rate/concurrency/quota limit. code: rate_limit_exceeded. Retry-After present.
503application/problem+jsonProblem503 — billing/admission/engine temporarily unavailable or same-key file intake is still in progress. codes: admission_unavailable, billing_unavailable, engine_unavailable, idempotency_in_progress. For idempotency_in_progress, Retry-After is present and the client safely retries the same key. Retry compute requests with the same `idempotency_key` in the request body; compute is not started when billing/DB is unavailable (fail-closed). Retry-After present.
Additional scopes
  • job.type == documentdocuments:process
  • job.type == transcriptiontranscriptions:create

DELETE/jobs/{job_id}/result

Delete a terminal result early

Returns 204 (also for repeated deletes). Requests deletion of the terminal payload and all its temporary copies (scrub/purge). Audit/ledger metadata is not deleted. An active job returns 409 `job_not_terminal`. Requires the product scope of the job plus `results:delete`.

Bearer token · Required scopes: results:deletedraft
Parameters, authentication and responses
Parameter
ParameterLocationTypeRequiredContract description
job_idpathstringRequired—
Responses
StatusContent typeResponseContract description
204——Result deleted (idempotent).
401application/problem+jsonProblem401 — invalid/expired/revoked key. code: invalid_key.
403application/problem+jsonProblem403 — the key lacks a required scope for its own resource. code: insufficient_scope.
404application/problem+jsonProblem404 — not found or foreign resource (also a purged tombstone). An opaque id does not replace authorization. code: resource_not_found.
409application/problem+jsonProblem409 — changed idempotency fingerprint, resource not ready/in use, or terminal cancel. codes: idempotency_conflict, result_not_ready, job_not_completed, job_already_terminal, job_not_terminal, file_in_use. A transient same-key intake already in progress uses 503 idempotency_in_progress with Retry-After, not an ambiguous conflict.
429application/problem+jsonProblem429 — rate/concurrency/quota limit. code: rate_limit_exceeded. Retry-After present.
503application/problem+jsonProblem503 — billing/admission/engine temporarily unavailable or same-key file intake is still in progress. codes: admission_unavailable, billing_unavailable, engine_unavailable, idempotency_in_progress. For idempotency_in_progress, Retry-After is present and the client safely retries the same key. Retry compute requests with the same `idempotency_key` in the request body; compute is not started when billing/DB is unavailable (fail-closed). Retry-After present.
Additional scopes
  • job.type == documentdocuments:process
  • job.type == transcriptiontranscriptions:create

POST/jobs/{job_id}/cancel

Request cooperative cancellation (idempotent)

Returns 202 + updated job when the cancellation request is accepted; 200 for an already `cancel_requested`/`cancelled` job; 409 `job_already_terminal` for completed/failed. Cancellation is cooperative: after `cancel_requested` a terminal `completed`/`failed` is still allowed. On terminal `cancelled` no partial clinical payload is published (`result_availability: unavailable`); any charge covers only explicitly defined started units listed in `Usage`, never future stages or a cancel penalty. Repeated cancel never double-refunds. Requires the product scope of the job plus `jobs:cancel`.

Bearer token · Required scopes: jobs:canceldraft
Parameters, authentication and responses
Parameter
ParameterLocationTypeRequiredContract description
job_idpathstringRequired—
Responses
StatusContent typeResponseContract description
200application/jsonJobAlready cancel_requested/cancelled (idempotent).
202application/jsonJobCancellation accepted; cooperative cancellation in progress.
401application/problem+jsonProblem401 — invalid/expired/revoked key. code: invalid_key.
403application/problem+jsonProblem403 — the key lacks a required scope for its own resource. code: insufficient_scope.
404application/problem+jsonProblem404 — not found or foreign resource (also a purged tombstone). An opaque id does not replace authorization. code: resource_not_found.
409application/problem+jsonProblem409 — changed idempotency fingerprint, resource not ready/in use, or terminal cancel. codes: idempotency_conflict, result_not_ready, job_not_completed, job_already_terminal, job_not_terminal, file_in_use. A transient same-key intake already in progress uses 503 idempotency_in_progress with Retry-After, not an ambiguous conflict.
429application/problem+jsonProblem429 — rate/concurrency/quota limit. code: rate_limit_exceeded. Retry-After present.
503application/problem+jsonProblem503 — billing/admission/engine temporarily unavailable or same-key file intake is still in progress. codes: admission_unavailable, billing_unavailable, engine_unavailable, idempotency_in_progress. For idempotency_in_progress, Retry-After is present and the client safely retries the same key. Retry compute requests with the same `idempotency_key` in the request body; compute is not started when billing/DB is unavailable (fail-closed). Retry-After present.
Additional scopes
  • job.type == documentdocuments:process
  • job.type == transcriptiontranscriptions:create
OpenAPI components

Data schemas 75 schemas

Field names and types follow the OpenAPI contract.

AbsentValue

Contract description: Explicitly absent value with a typed reason, instead of a fabricated zero or empty success.

Schema fields 3
ParameterTypeRequiredContract description
typevalueRequired—
reasonvalueRequired—
textstring | nullOptional—

Age

Schema fields 2
ParameterTypeRequiredContract description
valueintegerRequired—
unitvalueRequired—

AudioSegmentLocator

Contract description: Audio locator expressed in seconds from the start of the original recording. end_seconds must be >= start_seconds (validated at runtime).

Schema fields 11
ParameterTypeRequiredContract description
typevalueRequired—
start_secondsnumberRequired—
end_secondsnumberRequired—
exact—Optional—
start—Optional—
end—Optional—
x—Optional—
y—Optional—
width—Optional—
height—Optional—
rotation—Optional—

BillableUnit

Contract description: One chargeable unit recorded against a Usage entry. `type` is the unit kind, `quantity` its amount (may be fractional for audio per the published rounding rule), `stage` the internal product stage that the public operation may map to. Internal retries never increase the charged quantity.

Schema fields 3
ParameterTypeRequiredContract description
typestringRequiredUnit kind, e.g. pages, audio_seconds. Extensible by additive values; not a closed enum.
quantitynumberRequiredBillable quantity. Fractional only where the product tariff explicitly publishes rounding (e.g. audio_seconds). No GA monetary/unit maximum is approved; any technical safety scalar is a draft candidate only.
stagestringRequiredProduct stage, e.g. document, transcription.

Billing

Contract description: Optional per-request cost ceiling supplied by the caller. The server always additionally applies its own bounded estimate and account/key spend caps; the effective ceiling is the minimum of all of them and can never be raised without a new authorized request.

Schema fields 1
ParameterTypeRequiredContract description
max_charge_minorintegerOptionalOptional caller cost ceiling in integer minor units (gross, before refund). Absent means the caller supplies no cap; an explicit `null` is rejected in this draft (use absence). No concrete product/GA money maximum is approved: any technical safety scalar added later is a draft candidate, not a published product limit.

CodedValue

Contract description: Coded qualitative result (e.g. 'not detected'). code is a STRING; a negative finding is never represented as numeric zero.

Schema fields 4
ParameterTypeRequiredContract description
typevalueRequired—
codestringRequired—
displaystring | nullOptional—
codingCodingOptional—

Coding

Contract description: A selected terminology code (or a mapping candidate). Codes are STRINGS even for numeric-looking terminologies such as SNOMED. mapping_status=verified requires a non-empty version, a curated (non-LLM) mapping source from the curated enum, a non-empty recorded context axis (or typed reference) and provenance carrying a non-empty source/profile/pipeline identifier; this rejects the LLM-suggestion/null/unavailable-as-verified and all-null-context shapes at schema level, while full dictionary membership/equivalence validation remains a runtime gate. Candidates (mapping_status=candidate) may legitimately carry an llm_suggestion source. source and standardized values carry separate codings because a converted value (e.g. different property/mass-vs-molar) does not keep the original code automatically.

Schema fields 9
ParameterTypeRequiredContract description
systemstring · uriRequiredTerminology system URI, e.g. http://loinc.org. The normative format:uri keyword is declared here and planned for enforcement by the approved Ajv validation gate; system-domain resolution/lookup (which release a code belongs to) remains a runtime/dictionary gate.
codestringRequired—
displaystring | nullOptional—
versionstring | nullOptional—
mapping_statusvalueRequired—
mapping_sourcevalueOptional—
relationshipvalueOptional—
provenanceCodingProvenanceOptional—
contextCodingContextOptional—

CodingContext

Contract description: Terminology context needed to judge a mapping (LOINC-style axes plus lab-specific context). At least one axis must carry an ACTUAL non-empty value, or an explicit typed reference must be supplied; a context whose axes are all null is rejected. Absence of a needed axis is expressed through Mapping.missing_context, not invented here. Context lookup is a runtime/dictionary concern; this schema only records what was actually known.

Schema fields 8
ParameterTypeRequiredContract description
componentstring | nullOptional—
propertystring | nullOptional—
time_aspectstring | nullOptional—
specimenstring | nullOptional—
scalestring | nullOptional—
methodstring | nullOptional—
measurement_standardstring | nullOptional—
referencestring | nullOptionalExplicit typed reference to a terminology context record; resolved by the runtime dictionary gate.

CodingProvenance

Contract description: Where a coding/candidate came from. For a verified Coding at least one non-empty source_id/source_ref/pipeline_version/profile_ref is required (enforced by Coding.verified).

Schema fields 5
ParameterTypeRequiredContract description
originOriginOptional—
source_idstring | nullOptional—
source_refstring | nullOptionalExplicit typed reference to the release/rule record backing the claim.
pipeline_versionstring | nullOptional—
profile_refstring | nullOptional—

Component

Schema fields 2
ParameterTypeRequiredContract description
namestringRequired—
valueComponentValueRequired—

ComponentValue

Contract description: Value of one composite component. Composite is deliberately excluded to keep the schema bounded (no recursive self-reference).

QuantityValue | CodedValue | TextValue | RangeValue | RatioValue | AbsentValue

CompositeValue

Contract description: Typed, bounded components (e.g. systolic/diastolic). Bounded by maxItems; no unbounded recursion.

Schema fields 2
ParameterTypeRequiredContract description
typevalueRequired—
componentsarray<Component>Required—

Confidence

Contract description: A numeric estimate is representable ONLY together with an explicit kind and a described methodology. There is no implicit or default value such as 0.99. An uncalibrated score must not be presented as the probability of being correct. kind=calibrated_probability additionally requires a non-empty measurement_ref: no calibration evidence may be imagined.

Schema fields 5
ParameterTypeRequiredContract description
kindvalueRequired—
scorenumberRequired—
methodologystringRequired—
measurement_refstring | nullOptional—
profile_refstring | nullOptional—

DecisionThreshold

Contract description: A guideline/decision threshold, kept separate from laboratory reference intervals. Requires an explicit source and version; jurisdiction is optional. Never used as a universal lab range.

Schema fields 11
ParameterTypeRequiredContract description
lownumber | nullOptional—
highnumber | nullOptional—
unitstring | nullOptional—
ucum_codestring | nullOptional—
codestring | nullOptional—
descriptionstring | nullOptional—
sourcestringRequired—
versionstringRequired—
jurisdictionstring | nullOptional—
applicabilityvalueOptional—
populationPopulationOptional—

DocumentInfo

Contract description: Measured document-level facts. `page_count` and `languages` are measured metadata and remain required. `detected_type` is optional and is present only when the `classification` feature was requested and classification was measured; when that feature is not requested it is absent. A `document_type_hint` neither requests classification nor creates this field. Runtime mapper logic must align response feature presence with the request; JSON Schema validates shape only.

Schema fields 3
ParameterTypeRequiredContract description
detected_typestringOptional—
page_countintegerRequired—
languagesarray<string>Required—

DocumentOptions

Contract description: Document-processing options. Defaults match RFC v6 01 §1.1. `split_oversized` is an internal step after the page threshold, not a separate public product. `max_pages_per_part` never increases the billable page count. Unknown/non-convertible units remain raw with a warning, never a fabricated conversion. How a document is read (text layer vs. image recognition) is NOT a client option: the service decides internally.

Schema fields 3
ParameterTypeRequiredContract description
split_oversizedbooleanOptional—
max_pages_per_partintegerOptional—
standardize_unitsbooleanOptional—

DocumentPart

Contract description: Bounded part manifest for an oversized-document split (RFC 01). Page ranges use ORIGINAL 1-based page numbers; evidence and warnings still reference original page IDs. `status` describes only this part, not the whole operation. Unknown additive response metadata is tolerated. Consistency with coverage/quality is a runtime check, not schema-proven, and no pipeline build is claimed.

Schema fields 5
ParameterTypeRequiredContract description
part_idstringRequired—
page_startintegerRequired—
page_endintegerRequired—
statusstringRequired—
qualityQualityOptional—

DocumentRequest

Contract description: JSON body of POST /documents: exactly one FileSource plus the shared non-file fields. Unknown fields are rejected. One document in; the service decides how to read it.

Schema fields 8
ParameterTypeRequiredContract description
idempotency_keyIdempotencyKeyRequired—
wait_secondsintegerOptionalMaximum time to wait for a completed result after the job is durably accepted. 0 returns the job immediately; 1–10 may return the result directly, otherwise the accepted job is returned.
featuresarray<string>OptionalNon-empty unique feature set. Fixed default does not mean 'all future features'. Requesting `classification` permits a measured `document_info.detected_type`; without it that field is absent. `document_type_hint` is only a hint and never enables classification. The runtime mapper must enforce this request/response relationship; the schema does not infer it from a separate request.
document_type_hintstringOptionalOptional hint; never substitutes for the actual detected classification.
languagesarray<value> | array<string>Optional`auto` must not be mixed with explicit languages. Explicit support is ru/en in the draft.
optionsDocumentOptionsOptional—
billingBillingOptional—
fileFileSourceRequired—

DocumentRequestFields

Contract description: Non-file fields of POST /documents. Reused verbatim as the JSON `request` part of a multipart upload, so the file and processing options can be submitted in one request. `idempotency_key` is required. `wait_seconds` requests a bounded synchronous wait; if the result is not ready by then, the response contains the accepted job. Requested features return their typed object; unrequested features are absent. `classification` alone controls whether `document_info.detected_type` may be emitted; an unrequested classification means that field is absent, and `document_type_hint` never requests or forces classification. The public request never chooses text-vs-image processing — the service decides that internally. A request is never silently downgraded to another product/tariff. `languages` cannot mix `auto` with explicit languages.

Schema fields 7
ParameterTypeRequiredContract description
idempotency_keyIdempotencyKeyRequired—
wait_secondsintegerOptionalMaximum time to wait for a completed result after the job is durably accepted. 0 returns the job immediately; 1–10 may return the result directly, otherwise the accepted job is returned.
featuresarray<string>OptionalNon-empty unique feature set. Fixed default does not mean 'all future features'. Requesting `classification` permits a measured `document_info.detected_type`; without it that field is absent. `document_type_hint` is only a hint and never enables classification. The runtime mapper must enforce this request/response relationship; the schema does not infer it from a separate request.
document_type_hintstringOptionalOptional hint; never substitutes for the actual detected classification.
languagesarray<value> | array<string>Optional`auto` must not be mixed with explicit languages. Explicit support is ru/en in the draft.
optionsDocumentOptionsOptional—
billingBillingOptional—

DocumentResult

Contract description: Final document payload, identical for the short sync response and GET /jobs/{job_id}/result. One document in, one JSON result out: the service decides internally whether the text came from a text layer or image recognition, and the public result never exposes that distinction. Only requested features are present: `text` exists only when the `text` feature was requested and produced, `layout` only when `layout` was requested and measured. `document_info.page_count` and `languages` are unconditional measured metadata; `detected_type` is present only when `classification` was requested and measured, otherwise absent. `document_type_hint` never forces classification. Runtime mapper tests must enforce feature/output consistency; this result schema cannot compare with the separate request and makes no cross-request guarantee. Each substantive fact carries origin/evidence (medical lane); extraction never invents a verified international code. A completed product always carries settled usage; `quality.status` here is complete|partial only (a failed result is never published as completed). Type discriminates the result union. Unknown additive response fields are tolerated, but host emitters remain bound by a privacy-safe allowlist and clients must not process unknown clinical metadata.

Schema fields 16
ParameterTypeRequiredContract description
typevalueRequired—
idOpaqueIdRequired—
job_idOpaqueIdRequired—
statusvalueRequired—
created_atTimestampRequired—
completed_atTimestampRequired—
expires_atTimestampRequired—
document_infoDocumentInfoRequired—
textTextOptional—
biomarkersarray<Observation>Optional—
entitiesarray<Entity>Optional—
layoutarray<LayoutPage>OptionalPresent only when `layout` was requested and actually measured.
partsarray<DocumentPart>OptionalOptional per-part manifest when an oversized document was split (RFC 01). Original page ids are preserved; runtime consistency with coverage/quality is not schema-proven.
qualityobjectRequired—
pipeline_versionstringRequired—
usageobjectRequired—

Entity

Contract description: An extracted clinical entity. category=diagnosis is reserved for the patient; family-history content must use category=family_history. This prevents a negated family finding from becoming a patient-confirmed diagnosis. When mapping.status is verified, codings[] must include a verified source-fact Coding; candidates or standardized-only codings do not satisfy this structural rule. Dictionary membership, source correspondence, and clinical safety still require mapper/golden-corpus gates. Unknown additive response metadata is tolerated, but is not itself a clinical fact.

Schema fields 13
ParameterTypeRequiredContract description
idMedicalOpaqueIdRequired—
categoryvalueRequired—
textstringRequired—
normalized_textstring | nullOptional—
assertionEntityAssertionRequired—
codingsarray<Coding>Required—
mappingMappingRequired—
originOriginRequired—
evidencearray<Evidence>Required—
review_requiredbooleanRequired—
confidenceConfidenceOptional—
observed_atMedicalDateNullableOptional—
extensionsExtensionsOptional—

EntityAssertion

Contract description: Assertion metadata. A negated or family-history finding must never be surfaced as a patient-confirmed diagnosis; experiencer is explicit and the Entity rules keep family content out of the diagnosis category.

Schema fields 4
ParameterTypeRequiredContract description
polarityvalueRequired—
certaintyvalueRequired—
temporalityvalueRequired—
experiencervalueRequired—

Evidence

Contract description: Evidence for an extracted fact. Every evidence item carries a non-empty source_id. Text quote/offset/page bbox facts also require a non-empty fragment_id; audio facts require a non-empty segment_id; page bbox requires a 1-based page_number. Coordinates/offsets are never fabricated for text-only extraction.

Schema fields 9
ParameterTypeRequiredContract description
originOriginRequired—
source_idstringRequired—
source_typevalueOptional—
fragment_idstring | nullOptional—
segment_idstring | nullOptional—
page_numberinteger | nullOptional1-based original page number; preserved across split.
source_textstring | nullOptional—
locatorEvidenceLocatorRequired—
confidenceConfidenceOptional—

EvidenceLocator

Contract description: Discriminated locator. Each variant carries the identifiers appropriate to its medium; the Evidence-level conditionals require fragment_id for text/page and segment_id for audio.

TextQuoteLocator | UnicodeOffsetLocator | PageBBoxLocator | AudioSegmentLocator

Extensions

Contract description: Bounded scalar-only metadata for non-clinical extensions. Clinical meaning must use the typed fields above; arbitrary objects/arrays are rejected.

object

File

Contract description: Immutable public file resource metadata. Lifecycle status: ready | rejected | deleted | expired. Media type is determined by probe/magic bytes, not by filename/Content-Type alone. Retention is a draft policy subject to load/legal confirmation.

Schema fields 9
ParameterTypeRequiredContract description
idOpaqueIdRequired—
statusstringRequired—
media_typestringRequired—
byte_sizeintegerRequired—
created_atTimestampRequired—
expires_atNullableTimestampOptional—
sourcestringOptional—
page_countinteger | nullOptional—
rejectionJobErrorOptional—

FileSource

Contract description: Exactly one input source for a compute operation: an immutable host `file_id` (preferred for sequential operations) or a bounded HTTPS `url` intake. `oneOf` forbids supplying both or neither. Base64, provider selection and caller-supplied account/environment/patient/user fields are NOT supported in R1. Remote URL intake additionally requires the `files:write` scope and a required `idempotency_key` in the request body; URL fetch is SSRF-guarded (HTTPS only, no private/loopback/link-local/metadata targets, bounded redirects/bytes/time).

object | object

FileUploadMetadata

Contract description: Optional JSON metadata part accompanying a multipart POST /files. It never carries a second binary source and never carries account/environment/patient/user ownership. Fields here are intentionally minimal pending the final intake contract.

Schema fields 2
ParameterTypeRequiredContract description
filenamestringOptional—
idempotency_keyIdempotencyKeyOptional—

FileUploadUrlRequest

Contract description: JSON body for POST /files remote-URL intake. The downloaded object becomes an immutable file snapshot after validation.

Schema fields 2
ParameterTypeRequiredContract description
idempotency_keyIdempotencyKeyRequired—
sourceobjectRequired—

IdempotencyKey

Contract description: Client-generated key for safely retrying the same request. Use a unique value for each distinct operation; do not include personal or medical information.

string

Interpretation

Contract description: Interpretation is a comparison against a stated basis, never an automatic clinical statement that the patient is healthy. applicability is REQUIRED. basis=document_reference_range means only that the value fell within/outside the range printed on the source document. There is no universal clinical normal: a laboratory comparison must point at reference_ranges[reference_range_index] and a threshold comparison must point at decision_thresholds[threshold_index].

Schema fields 5
ParameterTypeRequiredContract description
codevalueRequired—
basisvalueRequired—
applicabilityvalueRequired—
reference_range_indexinteger | nullOptional—
threshold_indexinteger | nullOptional—

Job

Contract description: Public durable job envelope (metadata/status only; no embedded medical payload). Execution state machine: queued -> processing -> completed | failed; queued -> cancelled; queued|processing -> cancel_requested -> cancelled | completed | failed. completed/failed/cancelled are immutable terminals. Result availability is separate from execution state: completed may be available | expired | deleted; failed/cancelled are always unavailable and expose no partial payload. Progress/ETA are advisory and nullable (never fabricated). Status/usage/time/error couplings are enforced here: active => reserved usage, no completed_at, no error; completed => settled usage, completed_at, no error; failed => released usage, terminal time, error; cancelled => released OR settled (with non-empty started units), terminal time, a safe cancellation error code. Which concrete started units may be settled is a runtime tariff/adapter decision, NOT a schema claim.

Schema fields 12
ParameterTypeRequiredContract description
idOpaqueIdRequired—
typestringRequired—
statusstringRequired—
progressinteger | nullOptionalAdvisory only. Null when no honest estimate exists.
created_atTimestampRequired—
updated_atTimestampOptional—
completed_atNullableTimestampOptional—
result_availabilitystringRequired—
status_urlstring · uriRequired—
result_urlstring · uriRequired—
errorJobErrorOptional—
usageUsageRequired—

JobError

Contract description: Safe terminal job error. Never a raw provider exception or medical payload. A failed/cancelled job exposes no partial result payload.

Schema fields 3
ParameterTypeRequiredContract description
codestringRequired—
retryablebooleanRequired—
request_idstringRequired—

JobResult

Contract description: Typed result union returned by GET /jobs/{job_id}/result and by a short-wait 200 submit. `type` discriminates: document | transcription. The union uses the same schemas as the synchronous response and shares one Usage model. No partial payload is exposed for failed/cancelled jobs.

DocumentResult | TranscriptionResult

LayoutBlock

Contract description: Layout block, present only when `layout` is requested and actually measured. Coordinates are normalized 0..1 after rotation; they are never fabricated.

Schema fields 4
ParameterTypeRequiredContract description
idstringRequired—
typestringRequired—
textstring | nullOptional—
bboxarray<number>Optional—

LayoutPage

Contract description: Per-page layout metadata. Page numbering is the original 1-based page (preserved across internal split).

Schema fields 5
ParameterTypeRequiredContract description
page_numberintegerRequired—
widthnumber | nullOptional—
heightnumber | nullOptional—
rotationinteger | nullOptional—
blocksarray<LayoutBlock>Required—

Mapping

Contract description: Mapping outcome for one fact. status=ambiguous requires an explicit missing_context list; the list MAY be empty when ambiguity comes from competing candidates despite a complete context, and missing axes must not be invented just to fill it. status=verified requires a dictionary version and a curated mapping source from the same curated enum as Coding, and the containing Observation/Entity must include at least one verified source-fact Coding in codings[]. Alternative options live in candidates[] and must not be silently promoted to codings[]: every candidate entry must have mapping_status candidate or ambiguous, never verified. Source-fact codings belong in codings[]; standardized.codings[] alone does not satisfy this shape rule. Dictionary membership, matching coding status, and source correspondence remain runtime mapper checks.

Schema fields 6
ParameterTypeRequiredContract description
statusvalueRequired—
missing_contextarray<value>Optional—
candidatesarray<Coding & object>Optional—
dictionary_versionstring | nullOptional—
mapping_sourcevalueOptional—
notesstring | nullOptional—

MedicalDate

Contract description: A medical date/time that preserves the precision actually observed. There is no default widening to a full instant. kind=datetime is a UTC instant (RFC 3339 with trailing Z); date/year_month/year are partial dates and must not be normalized to a fabricated timestamp. observed_at and reported_at are distinct concepts and either may be null. The source contract declares normative format keywords: date-time for datetime, date for calendar dates, plus bounded patterns. The approved Ajv validation gate is planned to enforce the declared formats; this draft edit does not establish CI integration, runtime, or clinical readiness. A pattern match alone is not semantic proof of calendar validity or UTC semantics.

Schema fields 2
ParameterTypeRequiredContract description
kindvalueRequired—
valuestringRequired—

MedicalDateNullable

Contract description: A medical date/time that may be explicitly null when unknown or not provided. Null must not be filled with a fabricated timestamp; precision stays as observed.

null | MedicalDate

MedicalOpaqueId

Contract description: Opaque identifier. Clients must not parse structure out of it.

string

MultipartDocumentRequest

Contract description: The single JSON `request` part of POST /documents multipart upload. It carries the same non-file fields as the JSON request, including `idempotency_key` and `wait_seconds`, and MUST NOT contain `file` (the binary `file` part is the only source). Validated by the same JSON Schema; no ambiguous string-to-boolean/array form coercion.

Schema fields 7
ParameterTypeRequiredContract description
idempotency_keyIdempotencyKeyRequired—
wait_secondsintegerOptionalMaximum time to wait for a completed result after the job is durably accepted. 0 returns the job immediately; 1–10 may return the result directly, otherwise the accepted job is returned.
featuresarray<string>OptionalNon-empty unique feature set. Fixed default does not mean 'all future features'. Requesting `classification` permits a measured `document_info.detected_type`; without it that field is absent. `document_type_hint` is only a hint and never enables classification. The runtime mapper must enforce this request/response relationship; the schema does not infer it from a separate request.
document_type_hintstringOptionalOptional hint; never substitutes for the actual detected classification.
languagesarray<value> | array<string>Optional`auto` must not be mixed with explicit languages. Explicit support is ru/en in the draft.
optionsDocumentOptionsOptional—
billingBillingOptional—

MultipartTranscriptionRequest

Contract description: The single JSON `request` part of multipart POST /transcriptions. Same non-file fields, including `idempotency_key` and `wait_seconds`, no `file`.

Schema fields 5
ParameterTypeRequiredContract description
idempotency_keyIdempotencyKeyRequired—
wait_secondsintegerOptionalMaximum time to wait for a completed result after the job is durably accepted. 0 returns the job immediately; 1–10 may return the result directly, otherwise the accepted job is returned.
languagestringOptionalSupported modes depend on provider/profile; `auto` returns the detected language.
optionsTranscriptionOptionsOptional—
billingBillingOptional—

Normalization

Contract description: Unit/value normalization outcome. A normalized or partially_normalized status requires a non-empty rule_id and rule_version; absence of data or an unsupported conversion must be reported as not_normalized/unsupported instead of a fabricated success.

Schema fields 6
ParameterTypeRequiredContract description
statusvalueRequired—
rule_idstring | nullOptional—
rule_versionstring | nullOptional—
source_value_typestring | nullOptional—
target_value_typestring | nullOptional—
messagestring | nullOptional—

NullableTimestamp

Contract description: A Timestamp that may be null (e.g. not yet terminal). The nullable union preserves the full UTC date-time shape; a null is a real 'no instant yet' and is never a fabricated time.

Timestamp | null

Observation

Contract description: One reusable Observation document for document analysis (release 1) and reference normalize (release 2). factor_code is nullable and must stay null for genuinely unknown analytes (no invented canonical factor). raw is always preserved; standardized is null unless a real normalization succeeded. If mapping.status is verified, codings[] must include a verified Coding for the source fact; candidates or standardized-only codings do not satisfy this structural requirement. Dictionary membership, matching coding status, source correspondence, and clinical safety remain runtime mapper/golden-corpus checks. observed_at/reported_at preserve partial-date precision; they are distinct from operation created_at. Unknown additive response metadata is tolerated, but is not itself a clinical fact.

Schema fields 21
ParameterTypeRequiredContract description
idMedicalOpaqueIdRequired—
factor_codestring | nullRequired—
display_namestring | nullOptional—
rawRawObservationRequired—
valueValueRequired—
standardizednull | StandardizedRequired—
normalizationNormalizationRequired—
codingsarray<Coding>Required—
mappingMappingRequired—
reference_rangesarray<ReferenceRange>Required—
decision_thresholdsarray<DecisionThreshold>Required—
interpretationnull | InterpretationRequired—
observed_atMedicalDateNullableOptional—
reported_atMedicalDateNullableOptional—
patient_contextPatientContextOptional—
originOriginRequired—
evidencearray<Evidence>Optional—
review_requiredbooleanRequired—
warningsarray<Warning>Optional—
confidenceConfidenceOptional—
extensionsExtensionsOptional—

OpaqueId

Contract description: Opaque, account/environment-scoped identifier supplied by Lissa. It is a non-empty string, NOT forced to UUID; clients must treat it as opaque and never parse meaning or reuse it across accounts/environments. Authorization is checked independently of the identifier value (an opaque id does not replace authorization).

string

Origin

Contract description: Provenance of a fact: extracted from a source, inferred by a rule/model, or generated (e.g. synthesized text).

string

PageBBoxLocator

Contract description: Normalized bounding box 0..1 relative to the top-left of the original page after rotation. page_number (1-based) and rotation metadata live on Evidence. Bbox is emitted only when coordinates are actually available; never invented for text-only extraction.

Schema fields 11
ParameterTypeRequiredContract description
typevalueRequired—
xnumberRequired—
ynumberRequired—
widthnumberRequired—
heightnumberRequired—
rotationnumber | nullOptionalOptional page rotation metadata, degrees clockwise.
exact—Optional—
start—Optional—
end—Optional—
start_seconds—Optional—
end_seconds—Optional—

PatientContext

Contract description: Minimal, optional patient context, used only when a specific rule needs it. No patientId, name, caller identity or inferred sex. Gender identity is not mixed with laboratory context.

Schema fields 4
ParameterTypeRequiredContract description
age_at_observationAgeOptional—
sex_related_contextvalueOptional—
pregnancyboolean | nullOptional—
notestring | nullOptional—

Population

Contract description: Population applicability for a reference interval or threshold. Absence of patient context does not authorize applying a population range to the patient.

Schema fields 5
ParameterTypeRequiredContract description
age_mininteger | nullOptional—
age_maxinteger | nullOptional—
age_unitvalueOptional—
sexvalueOptional—
pregnancyboolean | nullOptional—

Problem

Contract description: RFC 9457 problem details document returned for typed errors (media type application/problem+json). `code` is a safe, machine-readable, PHI-free error code; known codes include invalid_request, insufficient_scope, invalid_key, insufficient_balance, spend_cap_exceeded, resource_not_found, idempotency_conflict, file_in_use, result_not_ready, job_not_completed, job_already_terminal, job_not_terminal, result_expired, result_deleted, payload_too_large, unsupported_media_type, validation_failed, rate_limit_exceeded, admission_unavailable, billing_unavailable, engine_unavailable, intake_timeout, document_unreadable, job_deadline_exceeded, internal_error. The code set is additive; it is not a closed enum. RFC 9457 extension members are permitted.

Schema fields 8
ParameterTypeRequiredContract description
typestring · uriRequiredProblem type URI; draft base https://lissa.health/problems/... is not a running service.
titlestringRequired—
statusintegerRequired—
detailstringOptionalHuman-readable, PHI-free. Never quotes a rejected value or medical content.
codestringRequiredSafe machine code (additive set, see description).
paramstring | nullOptionalOptional offending parameter name, e.g. `idempotency_key`.
request_idstringRequiredSafe request correlation id (also returned in X-Request-Id).
retryablebooleanRequired—

Quality

Contract description: Honest quality/coverage envelope for a result. complete | partial | failed. Coverage reports every missed page; warnings explain gaps. An empty result array means 'not found' only when coverage is sufficient. Confidence is never emitted without a described measurement method; a partial result is not a complete processing claim.

Schema fields 3
ParameterTypeRequiredContract description
statusstringRequired—
coverageobject | nullOptional—
warningsarray<QualityWarning>Required—

QualityWarning

Contract description: Safe, machine-readable quality warning. Optional locators point at the affected observation/fragment/page/segment. Warnings never fabricate confidence or a normalized value.

Schema fields 6
ParameterTypeRequiredContract description
codestringRequired—
observation_idstringOptional—
fragment_idstringOptional—
segment_idstringOptional—
page_numberintegerOptional—
messagestringOptional—

QuantityValue

Contract description: Numeric quantity. comparator=null means equality; '<' means the measured value is strictly below 'value' (censored/limit-of-detection style). unit is null when unknown; ucum_code is optional/nullable and must not be invented.

Schema fields 5
ParameterTypeRequiredContract description
typevalueRequired—
valuenumberRequired—
comparatorvalueRequired—
unitstring | nullOptional—
ucum_codestring | nullOptional—

RangeValue

Contract description: Interval result. At least one NUMERIC bound is required (a present-but-null bound does not count). Inclusive flags describe whether a bound is included; null means unknown.

Schema fields 7
ParameterTypeRequiredContract description
typevalueRequired—
lownumber | nullOptional—
highnumber | nullOptional—
low_inclusiveboolean | nullOptional—
high_inclusiveboolean | nullOptional—
unitstring | nullOptional—
ucum_codestring | nullOptional—

RatioValue

Contract description: Ratio such as a titre (1:160). The denominator must be non-zero.

Schema fields 5
ParameterTypeRequiredContract description
typevalueRequired—
numeratornumberRequired—
denominatornumberRequired—
unitstring | nullOptional—
ucum_codestring | nullOptional—

RawObservation

Contract description: Raw, unmodified source fields. The original name/value/unit/reference_range keys are ALWAYS present even when a standardized form exists; an individually unknown field is carried as null, never dropped or fabricated. notes is optional.

Schema fields 5
ParameterTypeRequiredContract description
namestring | nullRequired—
valuestring | nullRequired—
unitstring | nullRequired—
reference_rangestring | nullRequired—
notesstring | nullOptional—

ReferenceRange

Contract description: A laboratory or reference interval actually attached to a source. It is NOT a universal normal: applicability is REQUIRED and may be not_verified. A reference range must carry a meaningful value (at least one numeric bound or non-empty raw_text) and a non-empty source or source_id. A decision threshold is a separate object (DecisionThreshold).

Schema fields 14
ParameterTypeRequiredContract description
lownumber | nullOptional—
highnumber | nullOptional—
low_inclusiveboolean | nullOptional—
high_inclusiveboolean | nullOptional—
unitstring | nullOptional—
ucum_codestring | nullOptional—
raw_textstring | nullOptional—
sourcestring | nullOptional—
source_idstring | nullOptional—
contextstring | nullOptional—
applicabilityvalueRequired—
populationPopulationOptional—
observed_atMedicalDateNullableOptional—
time_aspectstring | nullOptional—

SpeakerConfidence

Contract description: Described confidence measurement for an inferred role. A numeric score is never emitted without a `kind` and `methodology`; calibrated and raw uncalibrated scores are distinct kinds. `calibrated` requires a non-empty calibration/profile reference. This is a local public definition and does not assume any medical-lane confidence shape.

Schema fields 4
ParameterTypeRequiredContract description
kindstringRequired—
methodologystringRequired—
profilestringOptionalCalibration/profile reference required for `calibrated`.
scorenumber | nullOptionalOnly meaningful with kind+methodology; never a bare score.

Standardized

Contract description: Normalized form of the same observation. Uses the SAME tagged Value union as value; codings are separate from the source codings because a converted value may change property/meaning.

Schema fields 2
ParameterTypeRequiredContract description
valueValueRequired—
codingsarray<Coding>Optional—

Text

Contract description: Extracted document text. Only requested/available representations are populated.

Schema fields 3
ParameterTypeRequiredContract description
plainstringRequired—
markdownstring | nullOptional—
fragmentsarray<TextFragment>Required—

TextFragment

Contract description: Contiguous text unit from the source text layer. `page_number` is 1-based and preserved across internal split. Locators are emitted only when actually available; a bbox/offset is never fabricated for text-only extraction.

Schema fields 5
ParameterTypeRequiredContract description
idstringRequired—
page_numberintegerRequired—
textstringRequired—
source_textstringOptional—
locatorobject | objectOptionalTyped locator. `text_quote` requires `exact`; `page_bbox` requires `bbox` [x0, y0, x1, y1] normalized 0..1 from top-left after rotation. Unknown additive metadata is tolerated, while known locator keys from the incompatible variant are explicitly rejected. Emitted only when actually available; ordering/consistency is a runtime check, not schema-proven.

TextQuoteLocator

Contract description: Verifiable fallback when coordinates are not available: an exact quote that must be unambiguous within the referenced fragment/source. Schema records the shape only; quote uniqueness and referential integrity are enforced at runtime.

Schema fields 11
ParameterTypeRequiredContract description
typevalueRequired—
exactstringRequired—
start—Optional—
end—Optional—
x—Optional—
y—Optional—
width—Optional—
height—Optional—
rotation—Optional—
start_seconds—Optional—
end_seconds—Optional—

TextValue

Contract description: Original qualitative text result preserved as-is.

Schema fields 2
ParameterTypeRequiredContract description
typevalueRequired—
textstringRequired—

Timestamp

Contract description: RFC 3339 date-time normalized to UTC with a trailing 'Z'. Operation created/completed/expiry timestamps are UTC instants; medical dates may be partial and are modelled separately, never coerced into a fabricated instant.

string · date-time

TranscriptionOptions

Contract description: Transcription options. Defaults match RFC v6 03 §1.1: diarize=true, timestamps_granularity=segment, role_attribution=none. Word-level timestamps have no output contract in R1, so `word` is DEFERRED from the R1 request shape (not silently allowed). `suggest` role attribution remains a valid gated request value, but the baseline must reject it with a typed error rather than fabricate roles. No profanity filtering by default.

Schema fields 3
ParameterTypeRequiredContract description
diarizebooleanOptional—
timestamps_granularitystringOptionalR1 emits `segment` only. A `word` profile is deferred until a word-level output contract exists and is not part of this draft shape.
role_attributionstringOptional`suggest` is a separate gated capability with uncertainty/evidence; baseline never infers identity and there is no caller role-confirmation input in R1.

TranscriptionRequest

Contract description: JSON body of POST /transcriptions: exactly one FileSource plus shared non-file fields.

Schema fields 6
ParameterTypeRequiredContract description
idempotency_keyIdempotencyKeyRequired—
wait_secondsintegerOptionalMaximum time to wait for a completed result after the job is durably accepted. 0 returns the job immediately; 1–10 may return the result directly, otherwise the accepted job is returned.
languagestringOptionalSupported modes depend on provider/profile; `auto` returns the detected language.
optionsTranscriptionOptionsOptional—
billingBillingOptional—
fileFileSourceRequired—

TranscriptionRequestFields

Contract description: Non-file fields of POST /transcriptions. Reused verbatim as the JSON `request` part of a multipart upload, so the audio and processing options can be submitted in one request. `idempotency_key` is required. `wait_seconds` requests a bounded synchronous wait; if the result is not ready by then, the response contains the accepted job.

Schema fields 5
ParameterTypeRequiredContract description
idempotency_keyIdempotencyKeyRequired—
wait_secondsintegerOptionalMaximum time to wait for a completed result after the job is durably accepted. 0 returns the job immediately; 1–10 may return the result directly, otherwise the accepted job is returned.
languagestringOptionalSupported modes depend on provider/profile; `auto` returns the detected language.
optionsTranscriptionOptionsOptional—
billingBillingOptional—

TranscriptionResult

Contract description: Transcription payload, identical for the short sync response and GET /jobs/{job_id}/result. `duration_seconds` is measured from the input audio; billable rounding is tariff-defined. Unintelligible/overlap/language-switch/unsure-dosage get warnings; no score is emitted without a described method (see SpeakerConfidence). Completed product => settled usage; `quality.status` here is complete|partial only.

Schema fields 15
ParameterTypeRequiredContract description
typevalueRequired—
idOpaqueIdRequired—
job_idOpaqueIdRequired—
statusvalueRequired—
created_atTimestampRequired—
completed_atTimestampRequired—
expires_atTimestampRequired—
duration_secondsnumberRequired—
languagestringRequiredDetected/handled language, e.g. ru, en.
textstringRequired—
segmentsarray<TranscriptionSegment>Required—
speakersarray<TranscriptionSpeaker>Required—
qualityobjectRequired—
pipeline_versionstringRequired—
usageobjectRequired—

TranscriptionSegment

Contract description: Timed text segment. Speaker id is nullable when the speaker is undetermined and is stable only within this result (never patient/doctor identity).

Schema fields 6
ParameterTypeRequiredContract description
idstringRequired—
indexintegerRequired—
speaker_idstring | nullOptional—
start_secondsnumberRequired—
end_secondsnumberRequired—
textstringRequired—

TranscriptionSpeaker

Contract description: Speaker entry. Role is `unknown` by default. `role_origin` records provenance: `not_assigned` (role must be `unknown`) or `inferred` (requires at least one non-empty evidence segment id and, if a score is given, a typed `confidence` object). Caller role confirmation is not an R1 input, so `client_confirmed` is not part of this draft shape. Array order is never confirmation.

Schema fields 5
ParameterTypeRequiredContract description
idstringRequired—
rolestringRequiredDefault `unknown`. Other values require a supported role-attribution profile.
role_originstringRequired—
evidence_segment_idsarray<string>Optional—
confidenceSpeakerConfidenceOptional—

UnicodeOffsetLocator

Contract description: Unicode code point offsets into the referenced text fragment. end is exclusive and must be >= start.

Schema fields 11
ParameterTypeRequiredContract description
typevalueRequired—
startintegerRequired—
endintegerRequired—
exact—Optional—
x—Optional—
y—Optional—
width—Optional—
height—Optional—
rotation—Optional—
start_seconds—Optional—
end_seconds—Optional—

Usage

Contract description: Unified prepaid usage ledger for every product. `status` is reserved | settled | released. Reserved: the full hold exists and charge_minor is null. Settled: a final gross charge is known (may be 0 for a partial/started-unit settlement) and it is the ONLY status where refund_minor may appear. Released: the hold is fully released, charge_minor is exactly 0 and there are no charged units (a hold release is not a refund). `simulation:true` never permits real money: reserved_minor and refund_minor are 0 and charge_minor is null or 0. reserved_minor is the held amount; net = charge_minor - refund_minor.

Schema fields 8
ParameterTypeRequiredContract description
statusstringRequired—
reserved_minorintegerRequired—
charge_minorinteger | nullRequiredFinal gross charge in integer minor units. Null only while status=reserved; 0 when released or when a settled run had no started units.
currencystringRequiredDraft: RUB only in R1; other ISO-4217 currencies require a new authorized contract.
pricing_versionstringRequiredPinned tariff/pricing version used for this operation. Draft placeholder values are illustrative, not published tariffs.
billable_unitsarray<BillableUnit>OptionalChronological billable units. Required for settled usage; a settled cancellation lists only started units and their stage. Released usage has no charged units (absent or empty).
refund_minorintegerOptionalOptional gross refund amount. Permitted only for settled usage; a hold release (released) is not a refund and must not carry this member.
simulationbooleanOptionalIndicates that this usage record reflects simulated processing. Simulated usage does not create a real charge.

Value

Contract description: Tagged union of observation value types. Every variant requires an explicit type tag; an unknown/absent value is absent, not numeric zero.

QuantityValue | CodedValue | TextValue | RangeValue | RatioValue | CompositeValue | AbsentValue

Warning

Schema fields 5
ParameterTypeRequiredContract description
codestringRequired—
messagestring | nullOptional—
severityvalueOptional—
observation_idstring | nullOptional—
entity_idstring | nullOptional—

ООО «Алвита» — разработчик Lissa Health