{ "openapi": "3.0.3", "info": { "title": "🧬 Labcore API", "version": "0.1.0", "description": "Labcore API runtime and event ingest." }, "servers": [ { "url": "/", "description": "Current LabCore host" } ], "tags": [ { "name": "docs", "description": "Swagger and OpenAPI documentation" }, { "name": "health", "description": "Service health" }, { "name": "orders", "description": "Atlas-compatible order creation and reads" }, { "name": "artifacts", "description": "Artifact metadata and downloads" }, { "name": "webhooks", "description": "Webhook registration and delivery inspection" }, { "name": "internal-events", "description": "Private runtime-to-LabCore milestone event ingest" } ], "paths": { "/": { "get": { "tags": ["docs"], "summary": "Open Swagger UI documentation", "operationId": "getSwaggerDocs", "responses": { "200": { "description": "Swagger UI HTML", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/openapi.json": { "get": { "tags": ["docs"], "summary": "Read the OpenAPI JSON specification", "operationId": "getOpenAPISpec", "responses": { "200": { "description": "OpenAPI JSON document", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/healthz": { "get": { "tags": ["health"], "summary": "Check service health", "operationId": "getHealthz", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "example": "ok" } } } } } } } } }, "/api/ext/v1/orders": { "post": { "tags": ["orders"], "summary": "Create an order", "operationId": "createOrder", "security": [ { "customerBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreateRequest" } } } }, "responses": { "201": { "description": "Order persisted and Temporal workflow started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "502": { "description": "Temporal workflow start failed after order persistence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreateResponse" } } } } } }, "get": { "tags": ["orders"], "summary": "List orders by exactly one supported reference filter", "operationId": "listOrders", "security": [ { "customerBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/CustomerOrderID" }, { "$ref": "#/components/parameters/CustomerCaseID" }, { "$ref": "#/components/parameters/CustomerPatientID" }, { "$ref": "#/components/parameters/BloomContainerEUID" }, { "$ref": "#/components/parameters/BloomSpecimenEUID" }, { "$ref": "#/components/parameters/ShipmentBarcode" }, { "$ref": "#/components/parameters/TestkitBarcode" }, { "$ref": "#/components/parameters/TRFEUID" }, { "$ref": "#/components/parameters/TestEUID" } ], "responses": { "200": { "description": "Matching order projections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/ext/v1/orders/{id}": { "get": { "tags": ["orders"], "summary": "Read order detail by internal order ID or TRF EUID", "operationId": "getOrder", "security": [ { "customerBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/ID" } ], "responses": { "200": { "description": "Order projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderReadResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": ["orders"], "summary": "Update an order with launch-scope comparator changes", "operationId": "updateOrder", "security": [ { "customerBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/ID" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderUpdateRequest" } } } }, "responses": { "200": { "description": "Order update accepted or replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderUpdateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/ext/v1/artifacts": { "get": { "tags": ["artifacts"], "summary": "List artifacts by exactly one supported reference filter", "operationId": "listArtifacts", "security": [ { "customerBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/CustomerOrderID" }, { "$ref": "#/components/parameters/CustomerCaseID" }, { "$ref": "#/components/parameters/CustomerPatientID" }, { "$ref": "#/components/parameters/BloomContainerEUID" }, { "$ref": "#/components/parameters/BloomSpecimenEUID" }, { "$ref": "#/components/parameters/ShipmentBarcode" }, { "$ref": "#/components/parameters/TestkitBarcode" }, { "$ref": "#/components/parameters/TRFEUID" }, { "$ref": "#/components/parameters/TestEUID" } ], "responses": { "200": { "description": "Matching artifact projections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/ext/v1/artifacts/{artifact_id}": { "get": { "tags": ["artifacts"], "summary": "Read artifact metadata", "operationId": "getArtifact", "security": [ { "customerBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/ArtifactID" } ], "responses": { "200": { "description": "Artifact projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactReadResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/ext/v1/artifacts/{artifact_id}/download-url": { "get": { "tags": ["artifacts"], "summary": "Mint a fetchable artifact download URL", "operationId": "getArtifactDownloadURL", "security": [ { "customerBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/ArtifactID" } ], "responses": { "200": { "description": "Artifact download URL and expiration metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactDownloadResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/downloads/artifacts/{artifact_id}": { "get": { "tags": ["artifacts"], "summary": "Download artifact bytes", "operationId": "downloadArtifact", "parameters": [ { "$ref": "#/components/parameters/ArtifactID" }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Artifact file bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/ext/v1/webhooks": { "post": { "tags": ["webhooks"], "summary": "Register a partner webhook endpoint", "operationId": "registerWebhook", "security": [ { "customerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRegistrationRequest" } } } }, "responses": { "201": { "description": "Webhook registration created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRegistrationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": ["webhooks"], "summary": "List active webhook registrations", "operationId": "listWebhooks", "security": [ { "customerBearer": [] } ], "responses": { "200": { "description": "Active webhook registrations without secrets", "content": { "application/json": { "schema": { "type": "object", "required": ["items", "total"], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookRegistrationResponse" } }, "total": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/ext/v1/webhooks/deliveries": { "get": { "tags": ["webhooks"], "summary": "List webhook delivery records", "operationId": "listWebhookDeliveries", "security": [ { "customerBearer": [] } ], "parameters": [ { "name": "event_id", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "sending", "delivered", "retry_scheduled", "failed" ] } }, { "name": "registration_id", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/TRFEUID" } ], "responses": { "200": { "description": "Webhook delivery records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/ext/v1/webhooks/deliveries/{id}": { "get": { "tags": ["webhooks"], "summary": "Read webhook delivery detail", "operationId": "getWebhookDelivery", "security": [ { "customerBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/ID" } ], "responses": { "200": { "description": "Webhook delivery detail with attempts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/internal/v1/events": { "post": { "tags": ["internal-events"], "summary": "Ingest a runtime workflow milestone event", "operationId": "ingestInternalEvent", "security": [ { "internalBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventEnvelope" }, "examples": { "alert": { "$ref": "#/components/examples/AlertWebhookEvent" }, "s3_artifact": { "$ref": "#/components/examples/S3ArtifactWebhookEvent" } } } } }, "responses": { "202": { "description": "Event persisted and matching deliveries queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventIngestResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/ext/v1/orders/{id}/cancel": { "post": { "tags": ["orders"], "summary": "Cancel an active order", "operationId": "cancelOrder", "security": [ { "customerBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/ID" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCancellationRequest" } } } }, "responses": { "200": { "description": "Order cancellation accepted or replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCancellationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } } }, "components": { "securitySchemes": { "customerBearer": { "type": "http", "scheme": "bearer", "description": "Fixed v0 customer bearer token from CUSTOMER_API_TOKEN." }, "internalBearer": { "type": "http", "scheme": "bearer", "description": "Private runtime-to-LabCore token from LABCORE_INTERNAL_TOKEN." } }, "parameters": { "RequestID": { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "type": "string" } }, "ID": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Internal resource ID. Order routes also accept the order trf_euid." }, "ArtifactID": { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string" } }, "CustomerOrderID": { "name": "customer_order_id", "in": "query", "schema": { "type": "string" } }, "CustomerCaseID": { "name": "customer_case_id", "in": "query", "schema": { "type": "string" } }, "CustomerPatientID": { "name": "customer_patient_id", "in": "query", "schema": { "type": "string" } }, "BloomContainerEUID": { "name": "bloom_container_euid", "in": "query", "schema": { "type": "string" } }, "BloomSpecimenEUID": { "name": "bloom_specimen_euid", "in": "query", "schema": { "type": "string" } }, "ShipmentBarcode": { "name": "shipment_barcode", "in": "query", "schema": { "type": "string" } }, "TestkitBarcode": { "name": "testkit_barcode", "in": "query", "schema": { "type": "string" } }, "TRFEUID": { "name": "trf_euid", "in": "query", "schema": { "type": "string" } }, "TestEUID": { "name": "test_euid", "in": "query", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } }, "OrderCreateRequest": { "type": "object", "required": [ "customer_order_id", "customer_case_id", "site_euid", "patients", "tests" ], "properties": { "customer_order_id": { "type": "string" }, "customer_case_id": { "type": "string" }, "order_type": { "type": "string", "example": "CLINICAL" }, "site_euid": { "type": "string" }, "clinical_notes": { "type": "string" }, "patients": { "type": "array", "items": { "$ref": "#/components/schemas/PatientCreateRequest" }, "minItems": 1 }, "tests": { "type": "array", "items": { "$ref": "#/components/schemas/OrderTestCreateRequest" }, "minItems": 1, "maxItems": 1 }, "external_refs": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRefRequest" } }, "metadata": { "type": "object", "additionalProperties": true }, "scenario": { "type": "string", "enum": [ "happy_path", "home_buccal_kit", "comparator_update", "cancellation", "shipping_failure_reshipment", "accessioning_irrecoverable_redraw", "accessioning_recoverable_missing_info", "accessioning_recoverable_mismatch", "accessioning_no_matching_order", "extraction_irrecoverable_redraw", "lc_irrecoverable_redraw", "rework_recovery_loop" ], "description": "Deterministic scenario selector. Defaults to happy_path." }, "proband_report_delivered_at": { "type": "string", "format": "date-time", "description": "Timestamp used to enforce the comparator update window." } }, "example": { "customer_order_id": "INFL-1001", "customer_case_id": "CASE-1001", "order_type": "CLINICAL", "site_euid": "SITE-LSMC", "scenario": "home_buccal_kit", "proband_report_delivered_at": "2026-04-08T12:00:00Z", "patients": [ { "role": "proband", "customer_patient_id": "INF-PT-001", "specimen_barcode": "BC-001", "collection_method": "home_buccal_kit", "demographics": { "first_name": "Ada", "last_name": "Lovelace", "date_of_birth": "1980-01-01", "sex": "F" } }, { "role": "mother", "customer_patient_id": "INF-PT-002", "specimen_barcode": "BC-002", "collection_method": "blood", "demographics": { "first_name": "Grace", "last_name": "Lovelace" } }, { "role": "father", "customer_patient_id": "INF-PT-003", "specimen_barcode": "BC-003", "collection_method": "blood", "demographics": { "first_name": "Alan", "last_name": "Lovelace" } } ], "tests": [ { "customer_test_id": "TEST-001", "fulfillment_routes": [ { "fulfillment_route_code": "WGS" } ], "specimen_type": "blood", "priority": "NORMAL" } ], "external_refs": [ { "namespace": "inflection", "kind": "shipment_barcode", "value": "SHIP-001", "target_hint": "order" } ] } }, "PatientCreateRequest": { "type": "object", "required": ["role", "customer_patient_id", "demographics"], "properties": { "role": { "type": "string", "example": "proband", "enum": ["proband", "mother", "father", "comparator"] }, "customer_patient_id": { "type": "string" }, "demographics": { "type": "object", "required": ["first_name", "last_name"], "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "date_of_birth": { "type": "string" }, "sex": { "type": "string" }, "mrn": { "type": "string" } } }, "specimen_barcode": { "type": "string" }, "collection_method": { "type": "string", "enum": ["blood", "home_buccal_kit"] } } }, "OrderTestCreateRequest": { "type": "object", "required": ["customer_test_id", "fulfillment_routes"], "properties": { "customer_test_id": { "type": "string" }, "fulfillment_routes": { "type": "array", "items": { "type": "object", "required": ["fulfillment_route_code"], "properties": { "fulfillment_route_code": { "type": "string", "example": "WGS" } } } }, "specimen_type": { "type": "string" }, "priority": { "type": "string" }, "clinical_notes": { "type": "string" } } }, "ExternalRefRequest": { "type": "object", "required": ["kind", "value"], "properties": { "namespace": { "type": "string" }, "kind": { "type": "string" }, "value": { "type": "string" }, "target_hint": { "type": "string" } } }, "OrderCreateResponse": { "type": "object", "required": [ "accepted", "idempotent_replay", "request_id", "trf", "tests", "identity_map" ], "properties": { "accepted": { "type": "boolean" }, "idempotent_replay": { "type": "boolean" }, "request_id": { "type": "string" }, "trf": { "$ref": "#/components/schemas/TRFResponse" }, "tests": { "type": "array", "items": { "$ref": "#/components/schemas/TestResponse" } }, "identity_map": { "$ref": "#/components/schemas/OrderCreateIdentityMap" } } }, "TRFResponse": { "type": "object", "properties": { "trf_euid": { "type": "string" }, "status": { "type": "string" } } }, "TestResponse": { "type": "object", "properties": { "test_euid": { "type": "string" }, "customer_test_id": { "type": "string" }, "status": { "type": "string" }, "product_code": { "type": "string" } } }, "OrderCreateIdentityMap": { "type": "object", "properties": { "customer_order_id": { "type": "string" }, "customer_case_id": { "type": "string" }, "patients": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityPatient" } }, "external_refs": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityExternalRef" } } } }, "IdentityPatient": { "type": "object", "properties": { "customer_patient_id": { "type": "string" }, "patient_euid": { "type": "string" }, "role": { "type": "string" }, "specimen_barcode": { "type": "string" }, "collection_method": { "type": "string" } } }, "IdentityExternalRef": { "type": "object", "properties": { "namespace": { "type": "string" }, "kind": { "type": "string" }, "value": { "type": "string" }, "target_type": { "type": "string" }, "target_euid": { "type": "string" } } }, "IdentityMap": { "type": "object", "properties": { "trf_euid": { "type": "string" }, "customer_order_id": { "type": "string" }, "customer_case_id": { "type": "string" }, "patients": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityPatient" } }, "bloom": { "type": "object", "properties": { "container_euids": { "type": "array", "items": { "type": "string" } }, "specimen_euids": { "type": "array", "items": { "type": "string" } } } }, "external_refs": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityExternalRef" } } } }, "OrderReadResponse": { "type": "object", "properties": { "identity_map": { "$ref": "#/components/schemas/IdentityMap" }, "order": { "$ref": "#/components/schemas/OrderResponse" }, "results": { "$ref": "#/components/schemas/ResultsResponse" } } }, "OrderListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderReadResponse" } }, "total": { "type": "integer" } } }, "OrderResponse": { "type": "object", "properties": { "trf_euid": { "type": "string" }, "status": { "type": "string" }, "tests": { "type": "array", "items": { "$ref": "#/components/schemas/TestResponse" } }, "scenario": { "type": "string", "enum": [ "happy_path", "home_buccal_kit", "comparator_update", "cancellation", "shipping_failure_reshipment", "accessioning_irrecoverable_redraw", "accessioning_recoverable_missing_info", "accessioning_recoverable_mismatch", "accessioning_no_matching_order", "extraction_irrecoverable_redraw", "lc_irrecoverable_redraw", "rework_recovery_loop" ] }, "proband_report_delivered_at": { "type": "string", "format": "date-time" }, "canceled_at": { "type": "string", "format": "date-time" }, "cancellation_reason": { "type": "string" } } }, "ResultsResponse": { "type": "object", "properties": { "release_authorized": { "type": "boolean" }, "release_packages": { "type": "array", "items": { "type": "object", "properties": { "package_euid": { "type": "string" }, "status": { "type": "string" } } } }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/Artifact" } } } }, "Artifact": { "type": "object", "properties": { "artifact_euid": { "type": "string" }, "filename": { "type": "string" }, "artifact_type": { "type": "string" }, "checksum": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" }, "source_system": { "type": "string" }, "source_uid": { "type": "string" }, "storage_uri": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "ArtifactReadResponse": { "type": "object", "properties": { "identity_map": { "$ref": "#/components/schemas/IdentityMap" }, "order": { "$ref": "#/components/schemas/OrderResponse" }, "artifact": { "$ref": "#/components/schemas/Artifact" }, "release_packages": { "type": "array", "items": { "type": "object" } } } }, "ArtifactListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactReadResponse" } }, "total": { "type": "integer" } } }, "ArtifactDownloadResponse": { "allOf": [ { "$ref": "#/components/schemas/ArtifactReadResponse" }, { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri" }, "expires_in_seconds": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" } } } ] }, "WebhookRegistrationRequest": { "type": "object", "required": ["url", "secret"], "properties": { "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "writeOnly": true }, "event_types": { "type": "array", "items": { "type": "string" } } } }, "WebhookRegistrationResponse": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "active": { "type": "boolean" }, "event_types": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } } }, "EventEnvelope": { "type": "object", "required": [ "event_id", "event_type", "event_name", "event_version", "occurred_at", "sent_at", "subject_type", "subject_id", "aggregate_type", "aggregate_id", "correlation_id", "payload" ], "properties": { "event_id": { "type": "string" }, "event_type": { "type": "string", "example": "E-37" }, "event_name": { "type": "string", "example": "accessioning_confirmed" }, "event_version": { "type": "string", "example": "1.0" }, "occurred_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": "string", "format": "date-time" }, "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "aggregate_type": { "type": "string" }, "aggregate_id": { "type": "string" }, "correlation_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true } }, "example": { "event_id": "M-EVT-96", "event_type": "E-37", "event_name": "accessioning_confirmed", "event_version": "1.0", "occurred_at": "2026-04-08T12:34:56Z", "sent_at": "2026-04-08T12:34:56Z", "subject_type": "specimen", "subject_id": "M-SPEC-4K", "aggregate_type": "order", "aggregate_id": "M-TRF-1V", "correlation_id": "INFL-1001", "payload": { "order": { "inflection_order_id": "INFL-1001", "lsmc_order_id": "M-TRF-1V", "trf_euid": "M-TRF-1V" }, "specimen": { "specimen_id": "M-SPEC-4K", "specimen_barcodes": ["BC-001"], "role": "proband" }, "accessioning": { "accession_id": "M-ACC-5Z", "collection_date_confirmed": true } } }, "description": "Partner-facing webhook envelope. event_id is stable for the same logical event and delivery retry set." }, "EventIngestResponse": { "type": "object", "properties": { "event_id": { "type": "string" }, "duplicate": { "type": "boolean" }, "queued_delivery_count": { "type": "integer" } } }, "WebhookDeliveryListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryResponse" } }, "total": { "type": "integer" } } }, "WebhookDeliveryResponse": { "type": "object", "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "registration_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "sending", "delivered", "retry_scheduled", "failed" ] }, "attempt_count": { "type": "integer" }, "next_attempt_at": { "type": "string", "format": "date-time" }, "last_error": { "type": "string" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookAttempt" } } } }, "WebhookAttempt": { "type": "object", "properties": { "id": { "type": "string" }, "attempt_number": { "type": "integer" }, "requested_at": { "type": "string", "format": "date-time" }, "response_status": { "type": "integer" }, "response_body_summary": { "type": "string" }, "error_summary": { "type": "string" }, "duration_millis": { "type": "integer", "format": "int64" }, "signature_headers": { "type": "object", "additionalProperties": true } } }, "OrderUpdatePatientRequest": { "type": "object", "required": ["role", "customer_patient_id"], "properties": { "role": { "type": "string", "enum": ["mother", "father", "comparator"] }, "customer_patient_id": { "type": "string" }, "specimen_barcode": { "type": "string" }, "collection_method": { "type": "string", "enum": ["blood", "home_buccal_kit"] }, "demographics": { "type": "object", "required": ["first_name", "last_name"], "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "date_of_birth": { "type": "string" }, "sex": { "type": "string" }, "mrn": { "type": "string" } } } } }, "OrderUpdateRequest": { "type": "object", "required": ["modification_type", "updated_by"], "properties": { "modification_type": { "type": "string", "enum": ["comparator_add", "comparator_remove"] }, "updated_by": { "type": "string" }, "patient": { "$ref": "#/components/schemas/OrderUpdatePatientRequest" }, "metadata": { "type": "object", "additionalProperties": true } }, "example": { "modification_type": "comparator_add", "updated_by": "inflection-api", "patient": { "role": "comparator", "customer_patient_id": "INF-PT-004", "specimen_barcode": "BC-004", "collection_method": "blood", "demographics": { "first_name": "Katherine", "last_name": "Johnson" } } } }, "OrderUpdateResponse": { "type": "object", "required": [ "accepted", "idempotent_replay", "request_id", "trf_euid", "modification_type", "status", "event_id" ], "properties": { "accepted": { "type": "boolean" }, "idempotent_replay": { "type": "boolean" }, "request_id": { "type": "string" }, "trf_euid": { "type": "string" }, "modification_type": { "type": "string" }, "status": { "type": "string" }, "event_id": { "type": "string" } } }, "OrderCancellationRequest": { "type": "object", "required": ["reason", "requested_by"], "properties": { "reason": { "type": "string" }, "requested_by": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } }, "example": { "reason": "provider_requested", "requested_by": "inflection-api" } }, "OrderCancellationResponse": { "type": "object", "required": [ "accepted", "idempotent_replay", "request_id", "trf_euid", "status", "event_id" ], "properties": { "accepted": { "type": "boolean" }, "idempotent_replay": { "type": "boolean" }, "request_id": { "type": "string" }, "trf_euid": { "type": "string" }, "status": { "type": "string" }, "event_id": { "type": "string" } } }, "LaunchAlertPayload": { "type": "object", "required": [ "alert_type", "severity", "recoverability", "requested_action", "affected_subject", "reason_code" ], "properties": { "alert_type": { "type": "string" }, "severity": { "type": "string" }, "recoverability": { "type": "string" }, "requested_action": { "type": "string" }, "affected_subject": { "type": "string" }, "reason_code": { "type": "string" } } }, "S3ArtifactPayload": { "type": "object", "required": [ "artifact_euid", "bucket", "key", "uri", "checksum", "size_bytes", "available_at" ], "properties": { "artifact_euid": { "type": "string" }, "bucket": { "type": "string" }, "key": { "type": "string" }, "uri": { "type": "string" }, "checksum": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" }, "available_at": { "type": "string", "format": "date-time" }, "mime_type": { "type": "string" }, "cram_filename": { "type": "string" } } } }, "examples": { "AlertWebhookEvent": { "summary": "Recoverable accessioning alert", "value": { "event_id": "M-EVT-A4", "event_type": "E-46", "event_name": "accessioning_missing_information_required", "event_version": "1.0", "occurred_at": "2026-04-08T12:34:56Z", "sent_at": "2026-04-08T12:35:02Z", "subject_type": "specimen", "subject_id": "M-SPEC-4K", "aggregate_type": "order", "aggregate_id": "M-TRF-1V", "correlation_id": "INFL-1001", "payload": { "order": { "inflection_order_id": "INFL-1001", "lsmc_order_id": "M-TRF-1V", "trf_euid": "M-TRF-1V" }, "specimen": { "specimen_id": "M-SPEC-4K", "specimen_barcodes": ["BC-001"], "role": "proband" }, "alert": { "alert_type": "accessioning_missing_information_required", "severity": "warning", "recoverability": "recoverable", "requested_action": "provide_missing_information", "affected_subject": "specimen", "reason_code": "missing_required_demographics" } } } }, "S3ArtifactWebhookEvent": { "summary": "Analysis data available with S3-shaped artifact fields", "value": { "event_id": "M-EVT-B2", "event_type": "E-67", "event_name": "analysis_data_available", "event_version": "1.0", "occurred_at": "2026-04-08T12:34:56Z", "sent_at": "2026-04-08T12:35:02Z", "subject_type": "artifact", "subject_id": "M-ART-6P", "aggregate_type": "order", "aggregate_id": "M-TRF-1V", "correlation_id": "INFL-1001", "payload": { "order": { "inflection_order_id": "INFL-1001", "lsmc_order_id": "M-TRF-1V", "trf_euid": "M-TRF-1V" }, "artifact": { "artifact_euid": "M-ART-6P", "bucket": "lsmc-artifacts", "key": "orders/M-TRF-1V/analysis/M-ART-6P", "uri": "s3://lsmc-artifacts/orders/M-TRF-1V/analysis/M-ART-6P", "checksum": "sha256:abc123", "size_bytes": 1048576, "available_at": "2026-04-08T12:35:02Z" } } } } } } }