{ "openapi": "3.1.0", "info": { "title": "Solia Partner API", "version": "v1", "description": "Server-to-server API for ordering laboratory diagnostics, tracking order\nlifecycle and retrieving released results.\n\nAuthentication: send your API key as `Authorization: Bearer `.\nKeys are environment-bound and scope-bound; a sandbox key can never reach\nproduction data.\n\nWebhook delivery semantics:\n- Delivery is at-least-once: the same event may arrive more than once.\n- Events may arrive out of order; use `sequence` from GET /v1/events to order them.\n- Subscribers must be idempotent on `event_id` and ignore a delivery id already seen.\n- Verify the HMAC-SHA256 signature over `.` before parsing.\n- Reject a delivery whose timestamp is outside a 5 minute tolerance.\n- The Partner API is authoritative: reconcile with GET /v1/events after any gap.\n\nWebhook events versus the authoritative API:\n- A webhook event carries identifiers and coarse state only. Analyte values, patient demographics, report documents, headers and secrets are never present.\n- The authoritative state is always the API: GET /v1/orders/{orderId}/results for released structured results, and GET /v1/orders/{orderId}/results/{resultId} for one version.\n- Deliveries are at-least-once and may arrive out of order. Deduplicate on event_id and treat the highest released result version from the API as current.\n- A missed or failed delivery never loses data: replay the ordered stream from GET /v1/events using the cursor, then re-read the results endpoint.\n- result.partial and result.final describe the same append-only lineage; a partial version remains retrievable after the final version is released.\n- result.corrected signals a new superseding version. The prior version is retained and reported as superseded rather than removed.\n- result.critical is an escalation signal only. Retrieve the critical workflow state and the observations from the result endpoint.\n- A report document is retrieved per request through the governed report endpoint. No permanent or signed document URL is ever delivered in an event." }, "servers": [], "security": [ { "PartnerApiKey": [] } ], "tags": [ { "name": "Health" }, { "name": "Laboratory" }, { "name": "Locations" }, { "name": "Programs" }, { "name": "Serviceability" }, { "name": "Subjects" }, { "name": "Orders" }, { "name": "Results" }, { "name": "Events" }, { "name": "Sandbox" } ], "paths": { "/v1/health": { "get": { "tags": [ "Health" ], "summary": "Verify credentials and environment", "responses": { "200": { "description": "The key is valid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "version": { "type": "string" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "server_time": { "type": "string", "format": "date-time" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/lab": { "get": { "tags": [ "Laboratory" ], "summary": "Retrieve the laboratory capability profile", "description": "Canonical, non-secret capability truth for the laboratory this key belongs to. Certification identifiers (CLIA, CAP) are not modeled in Solia today and are therefore reported as `not_modeled` rather than claimed, and the identity state is a laboratory self-declaration, never a verification.", "responses": { "200": { "description": "The capability profile.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/LabCapability" }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The key lacks `catalog:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/locations": { "get": { "tags": [ "Locations" ], "summary": "List externally serviceable collection locations", "description": "Only active locations in the service geography of the active programs this key is granted, in the current environment. Street address, telephone and internal operational detail are never returned.", "responses": { "200": { "description": "Serviceable locations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The key lacks `serviceability:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/programs": { "get": { "tags": [ "Programs" ], "summary": "List programs this key may order from", "responses": { "200": { "description": "Granted programs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Program" } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The key lacks `programs:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/programs/{programId}": { "get": { "tags": [ "Programs" ], "summary": "Retrieve one program", "parameters": [ { "name": "programId", "in": "path", "required": true, "description": "Program identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The program.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Program" }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown or ungranted program.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/programs/{programId}/catalog": { "get": { "tags": [ "Programs" ], "summary": "List orderable tests in a program", "parameters": [ { "name": "programId", "in": "path", "required": true, "description": "Program identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Orderable tests.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogItem" } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/serviceability": { "post": { "tags": [ "Serviceability" ], "summary": "Check whether a location and test can be fulfilled", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "program_id", "item_id" ], "properties": { "program_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "region": { "type": "string", "maxLength": 80 }, "collection": { "type": "string", "maxLength": 40 } } }, "example": { "program_id": "…", "item_id": "…", "region": "CA", "collection": "Mobile" } } } }, "responses": { "200": { "description": "Serviceability decision.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "serviceable": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/subjects/{externalSubjectId}": { "put": { "tags": [ "Subjects" ], "summary": "Register or update your opaque subject reference", "description": "Send only your own opaque identifier. Do not send names, dates of birth or clinical detail.", "parameters": [ { "name": "externalSubjectId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 190 } } ], "responses": { "200": { "description": "The subject link.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "external_subject_id": { "type": "string" }, "linked": { "type": "boolean" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/programs/{programId}/requirements": { "get": { "tags": [ "Programs" ], "summary": "Discover what an order must carry", "description": "Reports the laboratory's governed ordering requirements. A facet the laboratory has not configured is reported as `not_configured` and requires nothing.", "parameters": [ { "name": "programId", "in": "path", "required": true, "description": "Program identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "region", "in": "query", "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "200": { "description": "The governed requirement profile.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/OrderRequirements" }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown program for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sandbox/order-fixtures": { "get": { "tags": [ "Sandbox" ], "summary": "List synthetic order-request fixtures", "description": "Clearly synthetic request templates for the minimal, provider, patient and ask-at-order-entry contracts. Never real data.", "responses": { "200": { "description": "Synthetic fixtures.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "array", "items": { "type": "object" } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/orders": { "post": { "tags": [ "Orders" ], "summary": "Create an order", "description": "Send `Idempotency-Key`; a repeat with the same key returns the same order.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 190 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "external_order_id", "program_id", "item_id", "external_subject_id", "collection" ], "properties": { "external_order_id": { "type": "string", "maxLength": 190 }, "program_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "external_subject_id": { "type": "string", "maxLength": 190 }, "collection": { "type": "string", "maxLength": 40 }, "region": { "type": "string", "maxLength": 80 }, "patient": { "$ref": "#/components/schemas/PatientInput" }, "ordering_provider": { "$ref": "#/components/schemas/ProviderInput" }, "aoe_answers": { "type": "array", "items": { "$ref": "#/components/schemas/AoeAnswer" } }, "clinical_notes": { "type": "string", "maxLength": 2000 }, "billing_mode": { "type": "string", "maxLength": 40 }, "requested_collection_at": { "type": "string", "format": "date-time" }, "collection_location": { "type": "string", "maxLength": 190 } } } } } }, "responses": { "201": { "description": "The created order.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The idempotency key was reused with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "The program, test or subject is not orderable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited; honour `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/orders/{orderId}": { "get": { "tags": [ "Orders" ], "summary": "Retrieve order status", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Order identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The order.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown order for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/orders/{orderId}/cancel": { "post": { "tags": [ "Orders" ], "summary": "Cancel an order while cancellation is still possible", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Order identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The cancelled order.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The order has progressed too far to cancel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/orders/{orderId}/results": { "get": { "tags": [ "Results" ], "summary": "Retrieve released structured results", "description": "Released results only. An unreleased or in-progress result version is reported as pending and is never returned, whatever its internal status. Versions are append-only: a partial version stays retrievable after the final version is released, and a corrected or amended version supersedes rather than replaces the version before it. `version_lineage` states the current authoritative version and every superseded version. Observation values, units and reference intervals are exactly as the laboratory supplied them; LOINC is reported as `not_modeled` because Core holds no observation-level LOINC authority, and no code is ever derived.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Order identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Released results, if any.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "pending": { "type": "boolean" }, "pending_reason": { "type": [ "string", "null" ] }, "current_result_id": { "type": [ "string", "null" ], "format": "uuid" }, "current_version": { "type": [ "integer", "null" ] }, "version_lineage": { "type": "array", "items": { "$ref": "#/components/schemas/ResultVersion" } }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Result" } } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/orders/{orderId}/results/{resultId}": { "get": { "tags": [ "Results" ], "summary": "Retrieve one released result version in full", "description": "The same released-only boundary as the collection endpoint. An unreleased version is reported as not found rather than acknowledged.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Order identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "resultId", "in": "path", "required": true, "description": "Released result version identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The released result version.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Result" }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No released result version with this identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/orders/{orderId}/results/{resultId}/report": { "get": { "tags": [ "Results" ], "summary": "Retrieve the governed laboratory report for a released result", "description": "Authorization is identical to the result itself: the same key, client, Program, environment, order and released version. Retrieval is always server-authorized per request — there is no permanent public link, no signed document URL, and no document URL is ever placed in a webhook delivery or a log. When no canonical laboratory report document exists the response is an explicit refusal carrying `report_not_modeled`; a report is never fabricated.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Order identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "resultId", "in": "path", "required": true, "description": "Released result version identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Report availability and a short-lived, server-authorized retrieval path.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "result_id": { "type": "string", "format": "uuid" }, "report": { "$ref": "#/components/schemas/ReportAvailability" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The result is not released, or no canonical report document exists for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/orders/{orderId}/exceptions": { "get": { "tags": [ "Orders" ], "summary": "Read canonical specimen, sample and result exceptions", "description": "Normalized through the same canonical operational-exception architecture the laboratory operations surface uses — there is no second exception model. Structural fields only: operator notes, evidence and resolution text are never returned, and a laboratory-native vendor code is never guessed.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Order identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Canonical exceptions for this order, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "count": { "type": "integer" }, "action_required": { "type": "boolean" }, "exceptions": { "type": "array", "items": { "$ref": "#/components/schemas/OrderException" } } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/events": { "get": { "tags": [ "Events" ], "summary": "Read the event stream for reconciliation", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Events after the cursor, oldest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "request_id": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sandbox/scenarios": { "get": { "tags": [ "Sandbox" ], "summary": "List deterministic sandbox scenarios", "responses": { "200": { "description": "Available scenarios.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "scenario": { "type": "string", "enum": [ "happy_path", "partial_then_final", "specimen_rejection_recollection", "critical_result", "transmission_failure_then_retry", "corrected_result", "webhook_failure_then_replay", "specimen_rejected" ] }, "steps": { "type": "integer" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.created", "order.updated", "order.cancelled", "specimen.updated", "result.partial", "result.final", "result.corrected", "result.critical", "integration.action_required" ] } } } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sandbox/orders/{orderId}/simulate": { "post": { "tags": [ "Sandbox" ], "summary": "Advance a synthetic sandbox order through a scenario", "description": "Sandbox only. A production key or a non-synthetic order is refused.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Sandbox order identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scenario" ], "properties": { "scenario": { "type": "string", "enum": [ "happy_path", "partial_then_final", "specimen_rejection_recollection", "critical_result", "transmission_failure_then_retry", "corrected_result", "webhook_failure_then_replay", "specimen_rejected" ] } } } } } }, "responses": { "200": { "description": "Applied steps.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "scenario": { "type": "string" }, "events_emitted": { "type": "integer" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Simulation is not permitted for this key or order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sandbox/orders/{orderId}/laboratory-transport": { "post": { "tags": [ "Sandbox" ], "summary": "Send a synthetic sandbox order through the Solia test laboratory", "description": "Sandbox only. Sends the exact synthetic order through the real laboratory transport (canonical transmission, accepted ACK, signed inbound result). Requires the Sandbox laboratory to be the Solia test laboratory. Repeat calls are idempotent.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Sandbox order identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transport evidence for the order.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "transmission_id": { "type": [ "string", "null" ], "format": "uuid" }, "correlation_id": { "type": [ "string", "null" ] }, "transmission_status": { "type": [ "string", "null" ] }, "ack_status": { "type": [ "string", "null" ] }, "result_received": { "type": "boolean" }, "result_released": { "type": "boolean" }, "result_set_id": { "type": [ "string", "null" ], "format": "uuid" }, "result_status": { "type": [ "string", "null" ] }, "released_at": { "type": [ "string", "null" ], "format": "date-time" }, "event_id": { "type": [ "string", "null" ], "format": "uuid" }, "event_type": { "type": [ "string", "null" ] } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Client, environment or scope denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Transport is not permitted for this key, order or laboratory.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Per-instance client rate limit exceeded; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Canonical request failed; reconcile uncertain actions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Required API configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "webhooks": { "order.created": { "post": { "summary": "Delivery of order.created", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "order.updated": { "post": { "summary": "Delivery of order.updated", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "order.cancelled": { "post": { "summary": "Delivery of order.cancelled", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "specimen.updated": { "post": { "summary": "Delivery of specimen.updated", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "result.partial": { "post": { "summary": "Delivery of result.partial", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "result.final": { "post": { "summary": "Delivery of result.final", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "result.corrected": { "post": { "summary": "Delivery of result.corrected", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "result.critical": { "post": { "summary": "Delivery of result.critical", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "integration.action_required": { "post": { "summary": "Delivery of integration.action_required", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } } }, "components": { "securitySchemes": { "PartnerApiKey": { "type": "http", "scheme": "bearer", "description": "Scopes: programs:read, catalog:read, serviceability:read, subjects:write, orders:write, orders:read, orders:cancel, results:read, events:read, webhooks:manage." } }, "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error", "request_id" ], "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } }, "request_id": { "type": "string" } } }, "Program": { "type": "object", "properties": { "program_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "currency": { "type": [ "string", "null" ] } } }, "CatalogItem": { "type": "object", "description": "Canonical item identity and laboratory-native identity are distinct and both returned, together with mapping and orderable version provenance.", "properties": { "item_id": { "type": "string", "format": "uuid" }, "lab_orderable_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Populated only when exactly one active orderable is mapped; null for a multi-orderable panel — see provenance.mapped_orderables." }, "lab_test_code": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "external_code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "kind": { "type": [ "string", "null" ] }, "performing_laboratory": { "type": [ "string", "null" ] }, "specimen_type": { "type": [ "string", "null" ] }, "container": { "type": [ "string", "null" ] }, "min_volume_ml": { "type": [ "number", "null" ] }, "collection_methods": { "type": "array", "items": { "type": "string" } }, "preparation": { "type": [ "string", "null" ] }, "collection_instructions": { "type": "array", "description": "Supplied collection-method instructions. Distinct from specimen handling; empty when the laboratory supplied none.", "items": { "type": "object", "properties": { "method": { "type": "string" }, "instruction": { "type": "string" } } } }, "handling": { "type": [ "string", "null" ] }, "turnaround": { "type": [ "string", "null" ] }, "regions": { "type": "array", "items": { "type": "string" } }, "availability": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "price_visibility": { "type": "string", "enum": [ "visible", "hidden" ] }, "loinc": { "$ref": "#/components/schemas/TerminologyCode" }, "cpt": { "$ref": "#/components/schemas/TerminologyCode" }, "biomarkers": { "type": "array", "items": { "type": "string" } }, "markers": { "type": "array", "items": { "$ref": "#/components/schemas/Marker" } }, "aoe_requirement_refs": { "type": "array", "description": "Always empty: Solia has no canonical ask-at-order-entry storage yet. Generic clinical requirements are never relabelled as AOE.", "items": { "type": "string" } }, "mapping_version": { "type": [ "integer", "null" ] }, "orderable_version": { "type": [ "integer", "null" ] }, "status": { "type": [ "string", "null" ] }, "provenance": { "type": "object", "properties": { "item_id": { "type": "string", "format": "uuid" }, "mapping_version": { "type": [ "integer", "null" ] }, "mapping_status": { "type": [ "string", "null" ] }, "mapping_validation_status": { "type": [ "string", "null" ] }, "lab_orderable_id": { "type": [ "string", "null" ], "format": "uuid" }, "lab_test_code": { "type": [ "string", "null" ] }, "orderable_version": { "type": [ "integer", "null" ] }, "performing_laboratory": { "type": [ "string", "null" ] }, "mapped_orderables": { "type": "array", "description": "Every active governed mapping entry in canonical position order. A panel legitimately maps to several laboratory orderables.", "items": { "$ref": "#/components/schemas/MappedOrderable" } } } } } }, "LabCapability": { "type": "object", "properties": { "laboratory_id": { "type": [ "string", "null" ], "format": "uuid" }, "display_name": { "type": [ "string", "null" ] }, "legal_name": { "type": [ "string", "null" ] }, "operating_name": { "type": [ "string", "null" ] }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "certifications": { "type": "object", "description": "Not modeled canonically; no identifier is ever fabricated.", "properties": { "state": { "type": "string", "enum": [ "not_modeled" ] }, "identifiers": { "type": "array", "items": { "type": "string" } } } }, "jurisdictions": { "type": "array", "items": { "type": "string" } }, "service_geography": { "type": "array", "items": { "type": "string" } }, "collection_methods": { "type": "array", "description": "Collection-method keys only.", "items": { "type": "string" } }, "collection_modes": { "type": "array", "description": "Collection-mode keys only; a distinct canonical concept.", "items": { "type": "string" } }, "specimen_categories": { "type": "array", "items": { "type": "string" } }, "coding_systems_supplied": { "type": "array", "items": { "type": "string" } }, "reference_range_source": { "type": [ "string", "null" ] }, "standard_turnaround": { "type": [ "string", "null" ] }, "clinical_ordering_model": { "type": [ "string", "null" ] }, "laboratory_identity_state": { "type": "string", "description": "What the laboratory declared about itself. A self-declaration only — Solia stores no verification, accreditation or certification evidence.", "enum": [ "declared_laboratory", "declared_not_laboratory", "not_evaluated" ] } } }, "Location": { "type": "object", "properties": { "location_id": { "type": [ "string", "null" ], "format": "uuid" }, "location_code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "collection_methods": { "type": "array", "items": { "type": "string" } }, "appointment_required": { "type": [ "boolean", "null" ] }, "walk_in_allowed": { "type": [ "boolean", "null" ] }, "service_status": { "type": "string", "description": "Only serviceable locations are returned; inactive ones are omitted.", "enum": [ "active" ] } } }, "MappedOrderable": { "type": "object", "properties": { "lab_orderable_id": { "type": [ "string", "null" ], "format": "uuid" }, "lab_test_code": { "type": [ "string", "null" ] }, "panel_role": { "type": [ "string", "null" ] }, "is_required": { "type": [ "boolean", "null" ] }, "position": { "type": [ "integer", "null" ] }, "orderable_version": { "type": [ "integer", "null" ] }, "performing_laboratory": { "type": [ "string", "null" ] }, "specimen_type": { "type": [ "string", "null" ] }, "container": { "type": [ "string", "null" ] }, "min_volume_ml": { "type": [ "number", "null" ] }, "preparation": { "type": [ "string", "null" ] }, "handling": { "type": [ "string", "null" ] }, "turnaround": { "type": [ "string", "null" ] }, "regions": { "type": "array", "items": { "type": "string" } } } }, "TerminologyCode": { "type": "object", "description": "A code is only `mapped` when a governed mapping exists.", "properties": { "system": { "type": "string", "enum": [ "LOINC", "CPT" ] }, "code": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "mapped", "unmapped", "not_supplied" ] } } }, "Marker": { "type": "object", "properties": { "marker_id": { "type": [ "string", "null" ], "format": "uuid" }, "canonical_key": { "type": [ "string", "null" ] }, "lab_marker_code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "loinc": { "$ref": "#/components/schemas/TerminologyCode" }, "unit": { "type": [ "string", "null" ] }, "reference_range": { "type": [ "object", "null" ], "description": "Only supplied ranges are returned; none is ever inferred." }, "specimen_class": { "type": [ "string", "null" ] }, "mapping_state": { "type": "string", "enum": [ "approved", "mapped", "unmapped", "not_supplied" ] } } }, "Order": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "external_order_id": { "type": [ "string", "null" ] }, "program_id": { "type": [ "string", "null" ], "format": "uuid" }, "lifecycle": { "type": "string" }, "next_action": { "type": [ "string", "null" ] }, "lifecycle_detail": { "type": "string", "enum": [ "accepted", "requisition_created", "collection_scheduled", "sample_collected", "sample_in_transit", "sample_received", "processing", "partial_results", "final_results", "sample_error", "recollection_required", "cancelled", "action_required" ] }, "requisition": { "type": "object", "properties": { "state": { "type": [ "string", "null" ] }, "requisition_id": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "laboratory_reference": { "type": [ "string", "null" ] }, "document": { "type": "object", "description": "No canonical requisition document generator exists today.", "properties": { "state": { "type": "string", "enum": [ "not_modeled" ] } } } } }, "accession": { "type": [ "object", "null" ], "properties": { "accession_number": { "type": [ "string", "null" ] }, "accessioned_at": { "type": [ "string", "null" ], "format": "date-time" }, "received_at": { "type": [ "string", "null" ], "format": "date-time" }, "source_system": { "type": [ "string", "null" ] } } }, "specimens": { "type": "array", "description": "Specimen identifiers and states only; never patient identity.", "items": { "type": "object", "properties": { "specimen_id": { "type": [ "string", "null" ], "format": "uuid" }, "specimen_code": { "type": [ "string", "null" ] }, "specimen_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "collected_at": { "type": [ "string", "null" ], "format": "date-time" }, "received_at": { "type": [ "string", "null" ], "format": "date-time" }, "accession_number": { "type": [ "string", "null" ] }, "rejection_reason": { "type": [ "string", "null" ] }, "recollection_of": { "type": [ "string", "null" ], "format": "uuid" } } } }, "transmission": { "type": [ "object", "null" ], "properties": { "status": { "type": [ "string", "null" ] }, "attempt_no": { "type": [ "integer", "null" ] }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "ack_status": { "type": [ "string", "null" ] }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_order_ref": { "type": [ "string", "null" ] } } } } }, "PatientInput": { "type": "object", "description": "Sent only when the governed requirement profile asks for it. Written to the canonical subject record; never echoed in events or logs.", "properties": { "legal_first_name": { "type": "string", "maxLength": 120 }, "legal_last_name": { "type": "string", "maxLength": 120 }, "date_of_birth": { "type": "string", "format": "date" }, "sex_at_birth": { "type": "string", "maxLength": 40 }, "phone": { "type": "string", "maxLength": 40 }, "email": { "type": "string", "maxLength": 190 }, "region": { "type": "string", "maxLength": 80 }, "address_line1": { "type": "string", "maxLength": 190 }, "address_line2": { "type": "string", "maxLength": 190 }, "city": { "type": "string", "maxLength": 120 }, "postal_code": { "type": "string", "maxLength": 40 }, "country": { "type": "string", "maxLength": 80 } } }, "ProviderInput": { "type": "object", "description": "Either a canonical provider reference, or a name and NPI to resolve or register. Provider licences and jurisdictions are NOT modelled canonically, so none is accepted, validated or stored.", "properties": { "provider_reference": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 190 }, "npi": { "type": "string", "maxLength": 20 } } }, "AoeAnswer": { "type": "object", "required": [ "question_key", "answer" ], "description": "Answers your laboratory's own governed ask-at-order-entry questions. An answer to a question the laboratory does not define is refused.", "properties": { "question_key": { "type": "string", "maxLength": 120 }, "answer": { "type": "string", "maxLength": 500 } } }, "OrderRequirements": { "type": "object", "description": "Governed ordering requirements. `authority_state: not_configured` means the laboratory has configured no requirement for that facet, so it requires nothing; `not_modeled` means canonical Core carries no authority for that fact at all.", "properties": { "program_id": { "type": [ "string", "null" ], "format": "uuid" }, "item_id": { "type": [ "string", "null" ], "format": "uuid" }, "jurisdiction": { "type": [ "string", "null" ] }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "subject": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "opaque_reference", "identified" ] }, "required_patient_fields": { "type": "array", "items": { "type": "string" } }, "authority_state": { "type": "string", "enum": [ "configured", "not_configured" ] } } }, "order": { "type": "object", "properties": { "required_fields": { "type": "array", "items": { "type": "string" } }, "authority_state": { "type": "string", "enum": [ "configured", "not_configured" ] } } }, "provider": { "type": "object", "properties": { "requirement": { "type": "string", "enum": [ "not_required", "reference_required", "identified_required" ] }, "required_fields": { "type": "array", "items": { "type": "string" } }, "authority_state": { "type": "string", "enum": [ "configured", "not_configured" ] }, "license_authority_state": { "type": "string", "enum": [ "not_modeled" ] } } }, "aoe": { "type": "object", "properties": { "authority_state": { "type": "string", "enum": [ "configured", "not_configured" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "question_key": { "type": "string" }, "prompt": { "type": [ "string", "null" ] }, "answer_type": { "type": "string", "enum": [ "text", "number", "boolean", "date", "choice" ] }, "options": { "type": "array", "items": { "type": "string" } }, "required": { "type": "boolean" }, "version": { "type": [ "integer", "null" ] } } } } } }, "clinical": { "type": "object", "properties": { "policy": { "type": "string" }, "ordering_model": { "type": [ "string", "null" ] }, "clinical_review": { "type": [ "string", "null" ] }, "intake_required": { "type": [ "boolean", "null" ] }, "requirement_id": { "type": [ "string", "null" ], "format": "uuid" }, "requirement_state": { "type": "string", "enum": [ "configured", "not_configured" ] } } }, "collection": { "type": "object", "properties": { "methods": { "type": "array", "items": { "type": "string" } }, "regions": { "type": "array", "items": { "type": "string" } } } }, "billing": { "type": "object", "properties": { "mode_required": { "type": "boolean" }, "authority_state": { "type": "string", "enum": [ "configured", "not_configured" ] } } } } }, "Observation": { "type": "object", "description": "Exactly what the laboratory supplied, plus canonical mapping state. Values, units and reference intervals are never converted unless Core recorded a validated normalization, and `interpretation` normalizes only the laboratory's own flag.", "properties": { "observation_id": { "type": [ "string", "null" ], "format": "uuid" }, "canonical_biomarker_id": { "type": [ "string", "null" ] }, "biomarker_key": { "type": [ "string", "null" ] }, "lab_analyte_code": { "type": [ "string", "null" ] }, "terminology": { "type": "object", "properties": { "loinc": { "type": "object", "description": "Reported only as the laboratory supplied it. `not_modeled` means no code was supplied; a code is never derived.", "properties": { "system": { "type": "string", "enum": [ "LOINC" ] }, "code": { "type": [ "string", "null" ] }, "mapping_state": { "type": "string", "enum": [ "not_modeled", "supplied_by_laboratory" ] } } }, "snomed": { "type": "object", "description": "Supplied-only qualitative terminology. Never derived.", "properties": { "system": { "type": "string", "enum": [ "SNOMED-CT" ] }, "code": { "type": [ "string", "null" ] }, "mapping_state": { "type": "string", "enum": [ "not_modeled", "supplied_by_laboratory" ] } } } } }, "method": { "type": [ "string", "null" ] }, "observation_status": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "health_area": { "type": [ "string", "null" ] }, "result_type": { "type": "string", "enum": [ "numeric", "qualitative", "text", "not_supplied" ] }, "value_numeric": { "type": [ "number", "null" ] }, "value_qualitative": { "type": [ "string", "null" ] }, "value_text": { "type": [ "string", "null" ] }, "source_value": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "source_unit": { "type": [ "string", "null" ] }, "normalized": { "type": [ "object", "null" ], "description": "Present only when Core applied a validated conversion.", "properties": { "value": { "type": [ "number", "null" ] }, "unit": { "type": [ "string", "null" ] }, "method": { "type": "string" } } }, "mapping_state": { "type": [ "string", "null" ] }, "reference_low": { "type": [ "number", "null" ] }, "reference_high": { "type": [ "number", "null" ] }, "reference_text": { "type": [ "string", "null" ] }, "lab_flag": { "type": [ "string", "null" ] }, "interpretation": { "type": "string", "enum": [ "normal", "low", "high", "critical_low", "critical_high", "abnormal", "not_supplied", "unmapped" ] }, "is_critical": { "type": "boolean" }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "position": { "type": [ "integer", "null" ] } } }, "ResultVersion": { "type": "object", "description": "Append-only lineage entry. A superseded version is retained, never destroyed.", "properties": { "result_id": { "type": [ "string", "null" ], "format": "uuid" }, "version": { "type": [ "integer", "null" ] }, "version_type": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "partial", "final", "corrected", "amended" ] }, "released_at": { "type": [ "string", "null" ], "format": "date-time" }, "supersedes_result_id": { "type": [ "string", "null" ], "format": "uuid" }, "superseded_by_result_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_current": { "type": "boolean" } } }, "ReportAvailability": { "type": "object", "description": "Availability and an authenticated relative path only — never a signed or permanent document URL.", "properties": { "available": { "type": "boolean" }, "state": { "type": "string", "enum": [ "available", "not_available" ] }, "reason": { "type": [ "string", "null" ] }, "retrieval_path": { "type": [ "string", "null" ] } } }, "OrderException": { "type": "object", "description": "Canonical exception category with laboratory-native provenance. No free text.", "properties": { "exception_id": { "type": [ "string", "null" ], "format": "uuid" }, "category": { "type": "string", "enum": [ "specimen_rejected", "recollection_required", "collection_failed", "accession_missing", "transmission_failed", "acknowledgement_missing", "result_unmatched", "result_unknown", "result_normalization_failed", "catalog_mapping_required", "notification_failed", "provider_blocked", "critical_hold", "release_blocked", "other" ] }, "severity": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "owner_role": { "type": [ "string", "null" ] }, "entity_type": { "type": [ "string", "null" ] }, "opened_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "source": { "type": "object", "properties": { "exception_type": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "adapter_key": { "type": [ "string", "null" ] } } } } }, "Result": { "type": "object", "description": "One RELEASED result version with normalized observations. Critical state is only what the laboratory or the governed protocol declared; Solia adds no medical interpretation.", "properties": { "result_id": { "type": [ "string", "null" ], "format": "uuid" }, "order_id": { "type": [ "string", "null" ], "format": "uuid" }, "accession_id": { "type": [ "string", "null" ], "format": "uuid" }, "accession_number": { "type": [ "string", "null" ] }, "panel_item_id": { "type": [ "string", "null" ], "format": "uuid" }, "version": { "type": [ "integer", "null" ] }, "version_type": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "partial", "final", "corrected", "amended" ] }, "status": { "type": "string", "enum": [ "released", "not_released" ] }, "performing_laboratory": { "type": [ "string", "null" ] }, "performing_laboratory_system": { "type": [ "string", "null" ] }, "source_result_id": { "type": [ "string", "null" ] }, "source_provenance": { "type": [ "string", "null" ] }, "collected_at": { "type": [ "string", "null" ], "format": "date-time" }, "received_at": { "type": [ "string", "null" ], "format": "date-time" }, "resulted_at": { "type": [ "string", "null" ], "format": "date-time" }, "released_at": { "type": [ "string", "null" ], "format": "date-time" }, "supersedes_result_id": { "type": [ "string", "null" ], "format": "uuid" }, "completeness": { "type": [ "object", "null" ], "properties": { "state": { "type": [ "string", "null" ] }, "expected_count": { "type": [ "integer", "null" ] }, "received_count": { "type": [ "integer", "null" ] }, "unresolved_count": { "type": [ "integer", "null" ] }, "missing_biomarker_keys": { "type": "array", "items": { "type": "string" } } } }, "critical": { "type": "object", "properties": { "is_critical": { "type": "boolean" }, "workflow_status": { "type": [ "string", "null" ] }, "acknowledgement_state": { "type": [ "string", "null" ] }, "escalation_state": { "type": [ "string", "null" ] }, "responsible_role": { "type": [ "string", "null" ] }, "notified_at": { "type": [ "string", "null" ], "format": "date-time" }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "action_required": { "type": "boolean" } } }, "report": { "$ref": "#/components/schemas/ReportAvailability" }, "observation_count": { "type": "integer" }, "observations": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } } }, "Event": { "type": "object", "properties": { "event_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "order.created", "order.updated", "order.cancelled", "specimen.updated", "result.partial", "result.final", "result.corrected", "result.critical", "integration.action_required" ] }, "version": { "type": "integer" }, "occurred_at": { "type": "string", "format": "date-time" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "program_id": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "object", "description": "Identifiers and coarse state only — never values or demographics." } } } } } }