Laboratory orders

GET /lab-orders and GET /lab-orders/{id} reuse one authorised read service. Both require an explicitly granted read_lab_orders scope on a live practice API key. Patient, consultation and result grants do not imply it. Existing keys are not updated. Deployment and acceptance remain pending while the PR is draft.

List accepts only limit (default 20, maximum 100), offset (maximum 100000), patient_id, status and lab_provider_slug. Sort is created_at DESC, id DESC. A lookahead row determines has_more and next_offset. Offset pagination is not a consistent export snapshot under concurrent changes. Unknown, empty or repeated parameters return 422. An unavailable patient filter returns 404, including when it has no orders. Get accepts a UUID and no query parameters.

Both the order and joined patient must belong to the authorised practice. Responses project ID, patient ID, order number, provider slug, native test codes, sample date/time, workflow status and timestamps. Codes are bounded to 500 strings of at most 256 characters. Provider-specific snapshot JSON is not a harmonised test catalogue and is not exported. Sample time has no inferred timezone.

Statuses are ordered, sample_collected, sent_to_lab and cancelled. Consultation context is provenance, not a visibility switch; orders captured in draft consultations can exist independently on the record. Unknown states fail closed. Order status does not establish result finality, clinical review or completion of all requested tests. The creating user is not asserted to be a clinical requester.

Example: GET /lab-orders?patient_id=16247000-0000-4000-8000-000000000002&status=ordered&limit=20. List returns {data: [...], meta: {request_id, limit, has_more, next_offset}}; get returns {data: {...}, meta: {request_id}}. Successful reads use no-store. Provider payloads, copied demographics, insurance, clinical free text, credentials and URLs are outside the response contract.

First-party request logs retain key, practice and request attribution. Analytics use a fixed /api-v1/lab-orders label for this new resource, including unknown nested paths, without order IDs or query filters. General analytics cleanup is separate work in #15496.

Ordering, cancellation, results, tasks, MCP and FHIR are separate operations. This shared service does not claim FHIR conformance. Final-commit security/CI evidence and clinical/staging acceptance remain required before release.

curl -X GET "https://example.com/lab-orders"

{  "data": [    {      "id": "string",      "patient_id": "string",      "order_number": "string",      "status": "ordered",      "lab_provider_slug": "string",      "test_codes": [        "string"      ],      "sample_date": "string",      "sample_time": "string",      "created_at": "string",      "updated_at": "string",      "status_changed_at": "string"    }  ],  "meta": {    "request_id": "string",    "limit": 0,    "has_more": true,    "next_offset": 0  }}

curl -X GET "https://example.com/lab-orders/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "id": "string",    "patient_id": "string",    "order_number": "string",    "status": "ordered",    "lab_provider_slug": "string",    "test_codes": [      "string"    ],    "sample_date": "string",    "sample_time": "string",    "created_at": "string",    "updated_at": "string",    "status_changed_at": "string"  },  "meta": {    "request_id": "string"  }}