Перейти к содержимомуSkip to content

Справочник API ​

Здесь собраны методы API, параметры запросов, форматы ответов и схемы данных. Справочник построен по OpenAPI-контракту.

Публичный API пока недоступен для подключения. Отправка запросов со страницы отключена.

Базовый URLhttps://lissa.health/api/v1
Скачать OpenAPI
Методы API

Доступность

GET/health

Проверить доступность шлюза

Проверяет только доступность публичного шлюза. Успешный ответ не подтверждает готовность обработки документов, очередей или других сервисов.

Без авторизацииdraft
Параметры, авторизация и ответы
Ответы
СтатусФорматОтветОписание контракта (англ.)
200application/jsonобъектGateway 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.

Описание из исходного контракта (англ.)
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.

Методы API

Файлы

POST/files

Загрузить файл или передать ссылку

Создаёт неизменяемую копию файла для дальнейшей обработки. Поддерживаются бинарная загрузка и передача HTTPS-ссылки; повторная отправка зависит от ключа идемпотентности.

Bearer-токен · Разрешения: files:writedraftIdempotency-Key нужен для отдельных вариантов
Параметры, авторизация и ответы
Запрос
  • application/jsonFileUploadUrlRequestОбязательно
  • multipart/form-dataобъектОбязательно
Ответы
СтатусФорматОтветОписание контракта (англ.)
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 (англ.)

`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.

Описание из исходного контракта (англ.)
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.

GET/files/{file_id}

Получить состояние файла

Возвращает метаданные, состояние жизненного цикла и срок хранения файла.

Bearer-токен · Разрешения: files:readdraft
Параметры, авторизация и ответы
Параметр
ПараметрРасположениеТипОбязательноОписание контракта (англ.)
file_idpathстрокаОбязательно—
Ответы
СтатусФорматОтветОписание контракта (англ.)
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.

Описание из исходного контракта (англ.)
Returns metadata and lifecycle status (`ready|rejected|deleted|expired`), media type, actual bytes and retention. A foreign or non-existent id resolves to 404.

DELETE/files/{file_id}

Удалить файл

Удаляет файл. Если на него ссылается активное задание, сначала отмените задание или дождитесь его завершения.

Bearer-токен · Разрешения: files:writedraft
Параметры, авторизация и ответы
Параметр
ПараметрРасположениеТипОбязательноОписание контракта (англ.)
file_idpathстрокаОбязательно—
Ответы
СтатусФорматОтветОписание контракта (англ.)
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.

Описание из исходного контракта (англ.)
Returns 204. If active jobs still reference the file, returns 409 `file_in_use` — cancel/wait for terminal first.

Методы API

Документы

POST/documents

Обработать медицинский документ

Принимает один документ и возвращает структурированный результат: текст, данные о документе, классификацию и запрошенные медицинские факты. Обработка может завершиться сразу или продолжиться как фоновое задание.

Bearer-токен · Разрешения: documents:process, files:readdraftIdempotency-Key обязателен
Параметры, авторизация и ответы
Запрос
  • application/jsonDocumentRequestОбязательно
  • multipart/form-dataобъектОбязательно
Ответы
СтатусФорматОтветОписание контракта (англ.)
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.
Дополнительные разрешения
  • Источник — удалённая ссылкаfiles:write
  • В multipart/form-data передан новый бинарный файлfiles:write

Описание из исходного контракта (англ.)
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.

Методы API

Транскрибация

POST/transcriptions

Расшифровать аудиозапись

Преобразует аудио в текст с временными сегментами и, при включённой настройке, разделением по говорящим. Разделение голосов не определяет клинические роли.

Bearer-токен · Разрешения: transcriptions:create, files:readdraftIdempotency-Key обязателен
Параметры, авторизация и ответы
Запрос
  • application/jsonTranscriptionRequestОбязательно
  • multipart/form-dataобъектОбязательно
Ответы
СтатусФорматОтветОписание контракта (англ.)
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.
Дополнительные разрешения
  • Источник — удалённая ссылкаfiles:write
  • В multipart/form-data передан новый бинарный файлfiles:write

Описание из исходного контракта (англ.)
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.

Методы API

Задания

GET/jobs/{job_id}

Получить состояние задания

Возвращает состояние обработки, сведения об использовании и ссылку на результат. Медицинская полезная нагрузка в этом ответе не передаётся.

Bearer-токен · Разрешения: jobs:readdraft
Параметры, авторизация и ответы
Параметр
ПараметрРасположениеТипОбязательноОписание контракта (англ.)
job_idpathстрокаОбязательно—
Ответы
СтатусФорматОтветОписание контракта (англ.)
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.

Описание из исходного контракта (англ.)
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.

GET/jobs/{job_id}/result

Получить результат задания

Возвращает итоговый результат документа или транскрибации, если задание завершено и результат ещё доступен.

Bearer-токен · Разрешения: jobs:readdraft
Параметры, авторизация и ответы
Параметр
ПараметрРасположениеТипОбязательноОписание контракта (англ.)
job_idpathстрокаОбязательно—
Ответы
СтатусФорматОтветОписание контракта (англ.)
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.
Дополнительные разрешения
  • Тип задания — документdocuments:process
  • Тип задания — транскрибацияtranscriptions:create

Описание из исходного контракта (англ.)
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.

DELETE/jobs/{job_id}/result

Удалить результат задания

Удаляет итоговую полезную нагрузку и её временные копии. Аудитные и расчётные метаданные сохраняются.

Bearer-токен · Разрешения: results:deletedraft
Параметры, авторизация и ответы
Параметр
ПараметрРасположениеТипОбязательноОписание контракта (англ.)
job_idpathстрокаОбязательно—
Ответы
СтатусФорматОтветОписание контракта (англ.)
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.
Дополнительные разрешения
  • Тип задания — документdocuments:process
  • Тип задания — транскрибацияtranscriptions:create

Описание из исходного контракта (англ.)
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`.

POST/jobs/{job_id}/cancel

Запросить отмену задания

Запрашивает кооперативную отмену. Уже запущенный этап может завершиться до подтверждения отмены; частичный медицинский результат не публикуется.

Bearer-токен · Разрешения: jobs:canceldraft
Параметры, авторизация и ответы
Параметр
ПараметрРасположениеТипОбязательноОписание контракта (англ.)
job_idpathстрокаОбязательно—
Ответы
СтатусФорматОтветОписание контракта (англ.)
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.
Дополнительные разрешения
  • Тип задания — документdocuments:process
  • Тип задания — транскрибацияtranscriptions:create

Описание из исходного контракта (англ.)
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`.

OpenAPI components

Схемы данных 75 схемы

Имена полей и типы приведены по контракту OpenAPI. Подробные описания полей сохранены на языке исходной спецификации.

AbsentValue

Описание контракта (англ.): Explicitly absent value with a typed reason, instead of a fabricated zero or empty success.

Поля схемы 3
ПараметрТипОбязательноОписание контракта (англ.)
typevalueОбязательно—
reasonvalueОбязательно—
textstring | nullНеобязательно—

Age

Поля схемы 2
ПараметрТипОбязательноОписание контракта (англ.)
valueцелое числоОбязательно—
unitvalueОбязательно—

AudioSegmentLocator

Описание контракта (англ.): Audio locator expressed in seconds from the start of the original recording. end_seconds must be >= start_seconds (validated at runtime).

Поля схемы 11
ПараметрТипОбязательноОписание контракта (англ.)
typevalueОбязательно—
start_secondsчислоОбязательно—
end_secondsчислоОбязательно—
exact—Необязательно—
start—Необязательно—
end—Необязательно—
x—Необязательно—
y—Необязательно—
width—Необязательно—
height—Необязательно—
rotation—Необязательно—

BillableUnit

Описание контракта (англ.): 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.

Поля схемы 3
ПараметрТипОбязательноОписание контракта (англ.)
typeстрокаОбязательноUnit kind, e.g. pages, audio_seconds. Extensible by additive values; not a closed enum.
quantityчислоОбязательноBillable 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.
stageстрокаОбязательноProduct stage, e.g. document, transcription.

Billing

Описание контракта (англ.): 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.

Поля схемы 1
ПараметрТипОбязательноОписание контракта (англ.)
max_charge_minorцелое числоНеобязательноOptional 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

Описание контракта (англ.): Coded qualitative result (e.g. 'not detected'). code is a STRING; a negative finding is never represented as numeric zero.

Поля схемы 4
ПараметрТипОбязательноОписание контракта (англ.)
typevalueОбязательно—
codeстрокаОбязательно—
displaystring | nullНеобязательно—
codingCodingНеобязательно—

Coding

Описание контракта (англ.): 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.

Поля схемы 9
ПараметрТипОбязательноОписание контракта (англ.)
systemстрока · uriОбязательноTerminology 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.
codeстрокаОбязательно—
displaystring | nullНеобязательно—
versionstring | nullНеобязательно—
mapping_statusvalueОбязательно—
mapping_sourcevalueНеобязательно—
relationshipvalueНеобязательно—
provenanceCodingProvenanceНеобязательно—
contextCodingContextНеобязательно—

CodingContext

Описание контракта (англ.): 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.

Поля схемы 8
ПараметрТипОбязательноОписание контракта (англ.)
componentstring | nullНеобязательно—
propertystring | nullНеобязательно—
time_aspectstring | nullНеобязательно—
specimenstring | nullНеобязательно—
scalestring | nullНеобязательно—
methodstring | nullНеобязательно—
measurement_standardstring | nullНеобязательно—
referencestring | nullНеобязательноExplicit typed reference to a terminology context record; resolved by the runtime dictionary gate.

CodingProvenance

Описание контракта (англ.): 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).

Поля схемы 5
ПараметрТипОбязательноОписание контракта (англ.)
originOriginНеобязательно—
source_idstring | nullНеобязательно—
source_refstring | nullНеобязательноExplicit typed reference to the release/rule record backing the claim.
pipeline_versionstring | nullНеобязательно—
profile_refstring | nullНеобязательно—

Component

Поля схемы 2
ПараметрТипОбязательноОписание контракта (англ.)
nameстрокаОбязательно—
valueComponentValueОбязательно—

ComponentValue

Описание контракта (англ.): 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

Описание контракта (англ.): Typed, bounded components (e.g. systolic/diastolic). Bounded by maxItems; no unbounded recursion.

Поля схемы 2
ПараметрТипОбязательноОписание контракта (англ.)
typevalueОбязательно—
componentsмассив<Component>Обязательно—

Confidence

Описание контракта (англ.): 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.

Поля схемы 5
ПараметрТипОбязательноОписание контракта (англ.)
kindvalueОбязательно—
scoreчислоОбязательно—
methodologyстрокаОбязательно—
measurement_refstring | nullНеобязательно—
profile_refstring | nullНеобязательно—

DecisionThreshold

Описание контракта (англ.): 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.

Поля схемы 11
ПараметрТипОбязательноОписание контракта (англ.)
lownumber | nullНеобязательно—
highnumber | nullНеобязательно—
unitstring | nullНеобязательно—
ucum_codestring | nullНеобязательно—
codestring | nullНеобязательно—
descriptionstring | nullНеобязательно—
sourceстрокаОбязательно—
versionстрокаОбязательно—
jurisdictionstring | nullНеобязательно—
applicabilityvalueНеобязательно—
populationPopulationНеобязательно—

DocumentInfo

Описание контракта (англ.): 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.

Поля схемы 3
ПараметрТипОбязательноОписание контракта (англ.)
detected_typeстрокаНеобязательно—
page_countцелое числоОбязательно—
languagesмассив<строка>Обязательно—

DocumentOptions

Описание контракта (англ.): 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.

Поля схемы 3
ПараметрТипОбязательноОписание контракта (англ.)
split_oversizedлогическоеНеобязательно—
max_pages_per_partцелое числоНеобязательно—
standardize_unitsлогическоеНеобязательно—

DocumentPart

Описание контракта (англ.): 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.

Поля схемы 5
ПараметрТипОбязательноОписание контракта (англ.)
part_idстрокаОбязательно—
page_startцелое числоОбязательно—
page_endцелое числоОбязательно—
statusстрокаОбязательно—
qualityQualityНеобязательно—

DocumentRequest

Описание контракта (англ.): 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.

Поля схемы 8
ПараметрТипОбязательноОписание контракта (англ.)
idempotency_keyIdempotencyKeyОбязательно—
wait_secondsцелое числоНеобязательноMaximum 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.
featuresмассив<строка>НеобязательноNon-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_hintстрокаНеобязательноOptional hint; never substitutes for the actual detected classification.
languagesмассив<value> | массив<строка>Необязательно`auto` must not be mixed with explicit languages. Explicit support is ru/en in the draft.
optionsDocumentOptionsНеобязательно—
billingBillingНеобязательно—
fileFileSourceОбязательно—

DocumentRequestFields

Описание контракта (англ.): 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.

Поля схемы 7
ПараметрТипОбязательноОписание контракта (англ.)
idempotency_keyIdempotencyKeyОбязательно—
wait_secondsцелое числоНеобязательноMaximum 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.
featuresмассив<строка>НеобязательноNon-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_hintстрокаНеобязательноOptional hint; never substitutes for the actual detected classification.
languagesмассив<value> | массив<строка>Необязательно`auto` must not be mixed with explicit languages. Explicit support is ru/en in the draft.
optionsDocumentOptionsНеобязательно—
billingBillingНеобязательно—

DocumentResult

Описание контракта (англ.): 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.

Поля схемы 16
ПараметрТипОбязательноОписание контракта (англ.)
typevalueОбязательно—
idOpaqueIdОбязательно—
job_idOpaqueIdОбязательно—
statusvalueОбязательно—
created_atTimestampОбязательно—
completed_atTimestampОбязательно—
expires_atTimestampОбязательно—
document_infoDocumentInfoОбязательно—
textTextНеобязательно—
biomarkersмассив<Observation>Необязательно—
entitiesмассив<Entity>Необязательно—
layoutмассив<LayoutPage>НеобязательноPresent only when `layout` was requested and actually measured.
partsмассив<DocumentPart>НеобязательноOptional 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.
qualityобъектОбязательно—
pipeline_versionстрокаОбязательно—
usageобъектОбязательно—

Entity

Описание контракта (англ.): 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.

Поля схемы 13
ПараметрТипОбязательноОписание контракта (англ.)
idMedicalOpaqueIdОбязательно—
categoryvalueОбязательно—
textстрокаОбязательно—
normalized_textstring | nullНеобязательно—
assertionEntityAssertionОбязательно—
codingsмассив<Coding>Обязательно—
mappingMappingОбязательно—
originOriginОбязательно—
evidenceмассив<Evidence>Обязательно—
review_requiredлогическоеОбязательно—
confidenceConfidenceНеобязательно—
observed_atMedicalDateNullableНеобязательно—
extensionsExtensionsНеобязательно—

EntityAssertion

Описание контракта (англ.): 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.

Поля схемы 4
ПараметрТипОбязательноОписание контракта (англ.)
polarityvalueОбязательно—
certaintyvalueОбязательно—
temporalityvalueОбязательно—
experiencervalueОбязательно—

Evidence

Описание контракта (англ.): 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.

Поля схемы 9
ПараметрТипОбязательноОписание контракта (англ.)
originOriginОбязательно—
source_idстрокаОбязательно—
source_typevalueНеобязательно—
fragment_idstring | nullНеобязательно—
segment_idstring | nullНеобязательно—
page_numberinteger | nullНеобязательно1-based original page number; preserved across split.
source_textstring | nullНеобязательно—
locatorEvidenceLocatorОбязательно—
confidenceConfidenceНеобязательно—

EvidenceLocator

Описание контракта (англ.): 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

Описание контракта (англ.): Bounded scalar-only metadata for non-clinical extensions. Clinical meaning must use the typed fields above; arbitrary objects/arrays are rejected.

объект

File

Описание контракта (англ.): 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.

Поля схемы 9
ПараметрТипОбязательноОписание контракта (англ.)
idOpaqueIdОбязательно—
statusстрокаОбязательно—
media_typeстрокаОбязательно—
byte_sizeцелое числоОбязательно—
created_atTimestampОбязательно—
expires_atNullableTimestampНеобязательно—
sourceстрокаНеобязательно—
page_countinteger | nullНеобязательно—
rejectionJobErrorНеобязательно—

FileSource

Описание контракта (англ.): 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).

объект | объект

FileUploadMetadata

Описание контракта (англ.): 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.

Поля схемы 2
ПараметрТипОбязательноОписание контракта (англ.)
filenameстрокаНеобязательно—
idempotency_keyIdempotencyKeyНеобязательно—

FileUploadUrlRequest

Описание контракта (англ.): JSON body for POST /files remote-URL intake. The downloaded object becomes an immutable file snapshot after validation.

Поля схемы 2
ПараметрТипОбязательноОписание контракта (англ.)
idempotency_keyIdempotencyKeyОбязательно—
sourceобъектОбязательно—

IdempotencyKey

Описание контракта (англ.): Client-generated key for safely retrying the same request. Use a unique value for each distinct operation; do not include personal or medical information.

строка

Interpretation

Описание контракта (англ.): 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].

Поля схемы 5
ПараметрТипОбязательноОписание контракта (англ.)
codevalueОбязательно—
basisvalueОбязательно—
applicabilityvalueОбязательно—
reference_range_indexinteger | nullНеобязательно—
threshold_indexinteger | nullНеобязательно—

Job

Описание контракта (англ.): 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.

Поля схемы 12
ПараметрТипОбязательноОписание контракта (англ.)
idOpaqueIdОбязательно—
typeстрокаОбязательно—
statusстрокаОбязательно—
progressinteger | nullНеобязательноAdvisory only. Null when no honest estimate exists.
created_atTimestampОбязательно—
updated_atTimestampНеобязательно—
completed_atNullableTimestampНеобязательно—
result_availabilityстрокаОбязательно—
status_urlстрока · uriОбязательно—
result_urlстрока · uriОбязательно—
errorJobErrorНеобязательно—
usageUsageОбязательно—

JobError

Описание контракта (англ.): Safe terminal job error. Never a raw provider exception or medical payload. A failed/cancelled job exposes no partial result payload.

Поля схемы 3
ПараметрТипОбязательноОписание контракта (англ.)
codeстрокаОбязательно—
retryableлогическоеОбязательно—
request_idстрокаОбязательно—

JobResult

Описание контракта (англ.): 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

Описание контракта (англ.): Layout block, present only when `layout` is requested and actually measured. Coordinates are normalized 0..1 after rotation; they are never fabricated.

Поля схемы 4
ПараметрТипОбязательноОписание контракта (англ.)
idстрокаОбязательно—
typeстрокаОбязательно—
textstring | nullНеобязательно—
bboxмассив<число>Необязательно—

LayoutPage

Описание контракта (англ.): Per-page layout metadata. Page numbering is the original 1-based page (preserved across internal split).

Поля схемы 5
ПараметрТипОбязательноОписание контракта (англ.)
page_numberцелое числоОбязательно—
widthnumber | nullНеобязательно—
heightnumber | nullНеобязательно—
rotationinteger | nullНеобязательно—
blocksмассив<LayoutBlock>Обязательно—

Mapping

Описание контракта (англ.): 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.

Поля схемы 6
ПараметрТипОбязательноОписание контракта (англ.)
statusvalueОбязательно—
missing_contextмассив<value>Необязательно—
candidatesмассив<Coding & объект>Необязательно—
dictionary_versionstring | nullНеобязательно—
mapping_sourcevalueНеобязательно—
notesstring | nullНеобязательно—

MedicalDate

Описание контракта (англ.): 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.

Поля схемы 2
ПараметрТипОбязательноОписание контракта (англ.)
kindvalueОбязательно—
valueстрокаОбязательно—

MedicalDateNullable

Описание контракта (англ.): 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

Описание контракта (англ.): Opaque identifier. Clients must not parse structure out of it.

строка

MultipartDocumentRequest

Описание контракта (англ.): 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.

Поля схемы 7
ПараметрТипОбязательноОписание контракта (англ.)
idempotency_keyIdempotencyKeyОбязательно—
wait_secondsцелое числоНеобязательноMaximum 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.
featuresмассив<строка>НеобязательноNon-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_hintстрокаНеобязательноOptional hint; never substitutes for the actual detected classification.
languagesмассив<value> | массив<строка>Необязательно`auto` must not be mixed with explicit languages. Explicit support is ru/en in the draft.
optionsDocumentOptionsНеобязательно—
billingBillingНеобязательно—

MultipartTranscriptionRequest

Описание контракта (англ.): The single JSON `request` part of multipart POST /transcriptions. Same non-file fields, including `idempotency_key` and `wait_seconds`, no `file`.

Поля схемы 5
ПараметрТипОбязательноОписание контракта (англ.)
idempotency_keyIdempotencyKeyОбязательно—
wait_secondsцелое числоНеобязательноMaximum 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.
languageстрокаНеобязательноSupported modes depend on provider/profile; `auto` returns the detected language.
optionsTranscriptionOptionsНеобязательно—
billingBillingНеобязательно—

Normalization

Описание контракта (англ.): 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.

Поля схемы 6
ПараметрТипОбязательноОписание контракта (англ.)
statusvalueОбязательно—
rule_idstring | nullНеобязательно—
rule_versionstring | nullНеобязательно—
source_value_typestring | nullНеобязательно—
target_value_typestring | nullНеобязательно—
messagestring | nullНеобязательно—

NullableTimestamp

Описание контракта (англ.): 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

Описание контракта (англ.): 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.

Поля схемы 21
ПараметрТипОбязательноОписание контракта (англ.)
idMedicalOpaqueIdОбязательно—
factor_codestring | nullОбязательно—
display_namestring | nullНеобязательно—
rawRawObservationОбязательно—
valueValueОбязательно—
standardizednull | StandardizedОбязательно—
normalizationNormalizationОбязательно—
codingsмассив<Coding>Обязательно—
mappingMappingОбязательно—
reference_rangesмассив<ReferenceRange>Обязательно—
decision_thresholdsмассив<DecisionThreshold>Обязательно—
interpretationnull | InterpretationОбязательно—
observed_atMedicalDateNullableНеобязательно—
reported_atMedicalDateNullableНеобязательно—
patient_contextPatientContextНеобязательно—
originOriginОбязательно—
evidenceмассив<Evidence>Необязательно—
review_requiredлогическоеОбязательно—
warningsмассив<Warning>Необязательно—
confidenceConfidenceНеобязательно—
extensionsExtensionsНеобязательно—

OpaqueId

Описание контракта (англ.): 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).

строка

Origin

Описание контракта (англ.): Provenance of a fact: extracted from a source, inferred by a rule/model, or generated (e.g. synthesized text).

строка

PageBBoxLocator

Описание контракта (англ.): 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.

Поля схемы 11
ПараметрТипОбязательноОписание контракта (англ.)
typevalueОбязательно—
xчислоОбязательно—
yчислоОбязательно—
widthчислоОбязательно—
heightчислоОбязательно—
rotationnumber | nullНеобязательноOptional page rotation metadata, degrees clockwise.
exact—Необязательно—
start—Необязательно—
end—Необязательно—
start_seconds—Необязательно—
end_seconds—Необязательно—

PatientContext

Описание контракта (англ.): 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.

Поля схемы 4
ПараметрТипОбязательноОписание контракта (англ.)
age_at_observationAgeНеобязательно—
sex_related_contextvalueНеобязательно—
pregnancyboolean | nullНеобязательно—
notestring | nullНеобязательно—

Population

Описание контракта (англ.): Population applicability for a reference interval or threshold. Absence of patient context does not authorize applying a population range to the patient.

Поля схемы 5
ПараметрТипОбязательноОписание контракта (англ.)
age_mininteger | nullНеобязательно—
age_maxinteger | nullНеобязательно—
age_unitvalueНеобязательно—
sexvalueНеобязательно—
pregnancyboolean | nullНеобязательно—

Problem

Описание контракта (англ.): 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.

Поля схемы 8
ПараметрТипОбязательноОписание контракта (англ.)
typeстрока · uriОбязательноProblem type URI; draft base https://lissa.health/problems/... is not a running service.
titleстрокаОбязательно—
statusцелое числоОбязательно—
detailстрокаНеобязательноHuman-readable, PHI-free. Never quotes a rejected value or medical content.
codeстрокаОбязательноSafe machine code (additive set, see description).
paramstring | nullНеобязательноOptional offending parameter name, e.g. `idempotency_key`.
request_idстрокаОбязательноSafe request correlation id (also returned in X-Request-Id).
retryableлогическоеОбязательно—

Quality

Описание контракта (англ.): 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.

Поля схемы 3
ПараметрТипОбязательноОписание контракта (англ.)
statusстрокаОбязательно—
coverageobject | nullНеобязательно—
warningsмассив<QualityWarning>Обязательно—

QualityWarning

Описание контракта (англ.): Safe, machine-readable quality warning. Optional locators point at the affected observation/fragment/page/segment. Warnings never fabricate confidence or a normalized value.

Поля схемы 6
ПараметрТипОбязательноОписание контракта (англ.)
codeстрокаОбязательно—
observation_idстрокаНеобязательно—
fragment_idстрокаНеобязательно—
segment_idстрокаНеобязательно—
page_numberцелое числоНеобязательно—
messageстрокаНеобязательно—

QuantityValue

Описание контракта (англ.): 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.

Поля схемы 5
ПараметрТипОбязательноОписание контракта (англ.)
typevalueОбязательно—
valueчислоОбязательно—
comparatorvalueОбязательно—
unitstring | nullНеобязательно—
ucum_codestring | nullНеобязательно—

RangeValue

Описание контракта (англ.): 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.

Поля схемы 7
ПараметрТипОбязательноОписание контракта (англ.)
typevalueОбязательно—
lownumber | nullНеобязательно—
highnumber | nullНеобязательно—
low_inclusiveboolean | nullНеобязательно—
high_inclusiveboolean | nullНеобязательно—
unitstring | nullНеобязательно—
ucum_codestring | nullНеобязательно—

RatioValue

Описание контракта (англ.): Ratio such as a titre (1:160). The denominator must be non-zero.

Поля схемы 5
ПараметрТипОбязательноОписание контракта (англ.)
typevalueОбязательно—
numeratorчислоОбязательно—
denominatorчислоОбязательно—
unitstring | nullНеобязательно—
ucum_codestring | nullНеобязательно—

RawObservation

Описание контракта (англ.): 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.

Поля схемы 5
ПараметрТипОбязательноОписание контракта (англ.)
namestring | nullОбязательно—
valuestring | nullОбязательно—
unitstring | nullОбязательно—
reference_rangestring | nullОбязательно—
notesstring | nullНеобязательно—

ReferenceRange

Описание контракта (англ.): 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).

Поля схемы 14
ПараметрТипОбязательноОписание контракта (англ.)
lownumber | nullНеобязательно—
highnumber | nullНеобязательно—
low_inclusiveboolean | nullНеобязательно—
high_inclusiveboolean | nullНеобязательно—
unitstring | nullНеобязательно—
ucum_codestring | nullНеобязательно—
raw_textstring | nullНеобязательно—
sourcestring | nullНеобязательно—
source_idstring | nullНеобязательно—
contextstring | nullНеобязательно—
applicabilityvalueОбязательно—
populationPopulationНеобязательно—
observed_atMedicalDateNullableНеобязательно—
time_aspectstring | nullНеобязательно—

SpeakerConfidence

Описание контракта (англ.): 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.

Поля схемы 4
ПараметрТипОбязательноОписание контракта (англ.)
kindстрокаОбязательно—
methodologyстрокаОбязательно—
profileстрокаНеобязательноCalibration/profile reference required for `calibrated`.
scorenumber | nullНеобязательноOnly meaningful with kind+methodology; never a bare score.

Standardized

Описание контракта (англ.): 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.

Поля схемы 2
ПараметрТипОбязательноОписание контракта (англ.)
valueValueОбязательно—
codingsмассив<Coding>Необязательно—

Text

Описание контракта (англ.): Extracted document text. Only requested/available representations are populated.

Поля схемы 3
ПараметрТипОбязательноОписание контракта (англ.)
plainстрокаОбязательно—
markdownstring | nullНеобязательно—
fragmentsмассив<TextFragment>Обязательно—

TextFragment

Описание контракта (англ.): 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.

Поля схемы 5
ПараметрТипОбязательноОписание контракта (англ.)
idстрокаОбязательно—
page_numberцелое числоОбязательно—
textстрокаОбязательно—
source_textстрокаНеобязательно—
locatorобъект | объектНеобязательноTyped 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

Описание контракта (англ.): 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.

Поля схемы 11
ПараметрТипОбязательноОписание контракта (англ.)
typevalueОбязательно—
exactстрокаОбязательно—
start—Необязательно—
end—Необязательно—
x—Необязательно—
y—Необязательно—
width—Необязательно—
height—Необязательно—
rotation—Необязательно—
start_seconds—Необязательно—
end_seconds—Необязательно—

TextValue

Описание контракта (англ.): Original qualitative text result preserved as-is.

Поля схемы 2
ПараметрТипОбязательноОписание контракта (англ.)
typevalueОбязательно—
textстрокаОбязательно—

Timestamp

Описание контракта (англ.): 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.

строка · date-time

TranscriptionOptions

Описание контракта (англ.): 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.

Поля схемы 3
ПараметрТипОбязательноОписание контракта (англ.)
diarizeлогическоеНеобязательно—
timestamps_granularityстрокаНеобязательноR1 emits `segment` only. A `word` profile is deferred until a word-level output contract exists and is not part of this draft shape.
role_attributionстрокаНеобязательно`suggest` is a separate gated capability with uncertainty/evidence; baseline never infers identity and there is no caller role-confirmation input in R1.

TranscriptionRequest

Описание контракта (англ.): JSON body of POST /transcriptions: exactly one FileSource plus shared non-file fields.

Поля схемы 6
ПараметрТипОбязательноОписание контракта (англ.)
idempotency_keyIdempotencyKeyОбязательно—
wait_secondsцелое числоНеобязательноMaximum 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.
languageстрокаНеобязательноSupported modes depend on provider/profile; `auto` returns the detected language.
optionsTranscriptionOptionsНеобязательно—
billingBillingНеобязательно—
fileFileSourceОбязательно—

TranscriptionRequestFields

Описание контракта (англ.): 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.

Поля схемы 5
ПараметрТипОбязательноОписание контракта (англ.)
idempotency_keyIdempotencyKeyОбязательно—
wait_secondsцелое числоНеобязательноMaximum 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.
languageстрокаНеобязательноSupported modes depend on provider/profile; `auto` returns the detected language.
optionsTranscriptionOptionsНеобязательно—
billingBillingНеобязательно—

TranscriptionResult

Описание контракта (англ.): 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.

Поля схемы 15
ПараметрТипОбязательноОписание контракта (англ.)
typevalueОбязательно—
idOpaqueIdОбязательно—
job_idOpaqueIdОбязательно—
statusvalueОбязательно—
created_atTimestampОбязательно—
completed_atTimestampОбязательно—
expires_atTimestampОбязательно—
duration_secondsчислоОбязательно—
languageстрокаОбязательноDetected/handled language, e.g. ru, en.
textстрокаОбязательно—
segmentsмассив<TranscriptionSegment>Обязательно—
speakersмассив<TranscriptionSpeaker>Обязательно—
qualityобъектОбязательно—
pipeline_versionстрокаОбязательно—
usageобъектОбязательно—

TranscriptionSegment

Описание контракта (англ.): Timed text segment. Speaker id is nullable when the speaker is undetermined and is stable only within this result (never patient/doctor identity).

Поля схемы 6
ПараметрТипОбязательноОписание контракта (англ.)
idстрокаОбязательно—
indexцелое числоОбязательно—
speaker_idstring | nullНеобязательно—
start_secondsчислоОбязательно—
end_secondsчислоОбязательно—
textстрокаОбязательно—

TranscriptionSpeaker

Описание контракта (англ.): 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.

Поля схемы 5
ПараметрТипОбязательноОписание контракта (англ.)
idстрокаОбязательно—
roleстрокаОбязательноDefault `unknown`. Other values require a supported role-attribution profile.
role_originстрокаОбязательно—
evidence_segment_idsмассив<строка>Необязательно—
confidenceSpeakerConfidenceНеобязательно—

UnicodeOffsetLocator

Описание контракта (англ.): Unicode code point offsets into the referenced text fragment. end is exclusive and must be >= start.

Поля схемы 11
ПараметрТипОбязательноОписание контракта (англ.)
typevalueОбязательно—
startцелое числоОбязательно—
endцелое числоОбязательно—
exact—Необязательно—
x—Необязательно—
y—Необязательно—
width—Необязательно—
height—Необязательно—
rotation—Необязательно—
start_seconds—Необязательно—
end_seconds—Необязательно—

Usage

Описание контракта (англ.): 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.

Поля схемы 8
ПараметрТипОбязательноОписание контракта (англ.)
statusстрокаОбязательно—
reserved_minorцелое числоОбязательно—
charge_minorinteger | nullОбязательноFinal gross charge in integer minor units. Null only while status=reserved; 0 when released or when a settled run had no started units.
currencyстрокаОбязательноDraft: RUB only in R1; other ISO-4217 currencies require a new authorized contract.
pricing_versionстрокаОбязательноPinned tariff/pricing version used for this operation. Draft placeholder values are illustrative, not published tariffs.
billable_unitsмассив<BillableUnit>НеобязательноChronological 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_minorцелое числоНеобязательноOptional gross refund amount. Permitted only for settled usage; a hold release (released) is not a refund and must not carry this member.
simulationлогическоеНеобязательноIndicates that this usage record reflects simulated processing. Simulated usage does not create a real charge.

Value

Описание контракта (англ.): 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

Поля схемы 5
ПараметрТипОбязательноОписание контракта (англ.)
codeстрокаОбязательно—
messagestring | nullНеобязательно—
severityvalueНеобязательно—
observation_idstring | nullНеобязательно—
entity_idstring | nullНеобязательно—

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