{
  "$comment": "Generated from src/rail/operations.data.mjs by scripts/generate-agent-artifacts.mjs. Do not edit. An operation with a non-null `planned` is designed but not registered: the path answers 404 today, and the string says why.",
  "generated": "2026-09-02",
  "facilityHeaders": [
    {
      "name": "X-Facility-Id",
      "required": true,
      "description": "The facility this call is made from.",
      "example": "{{facility_code}}"
    },
    {
      "name": "X-Facility-Id-Type",
      "required": true,
      "description": "How to read X-Facility-Id: mfl, license-number, fr-code, registration-number or fid.",
      "example": "fr-code"
    }
  ],
  "counts": {
    "stops": 10,
    "operations": 44,
    "planned": 20,
    "callable": 24
  },
  "operations": [
    {
      "id": "auth.token",
      "stop": "authenticate",
      "stopLabel": "00 · Authenticate",
      "method": "POST",
      "path": "/realms/slade360/protocol/openid-connect/token",
      "liftedFrom": "apis/auth-API/openapi.json",
      "summary": "Exchange client credentials for an access token.",
      "keep": "access_token",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": "/auth-api"
    },
    {
      "id": "callbacks.register",
      "stop": "authenticate",
      "stopLabel": "00 · Authenticate",
      "method": "POST",
      "path": "/api/v1/callbacks",
      "liftedFrom": null,
      "summary": "Register webhook endpoints. Required before a claim may be submitted.",
      "keep": "callback_id",
      "requiresFacilityHeaders": false,
      "planned": "No /api/v1/callbacks route is registered in the service.",
      "reference": null
    },
    {
      "id": "identifier.types",
      "stop": "identify",
      "stopLabel": "01 · Identify",
      "method": "GET",
      "path": "/api/v1/terminology/concepts?code_system=IDENTIFIER-TYPES&version=serving",
      "liftedFrom": null,
      "summary": "The document types a desk may choose from today. Cache by version; never embed.",
      "keep": "codes[].code",
      "requiresFacilityHeaders": true,
      "planned": null,
      "reference": null
    },
    {
      "id": "patient.lookup",
      "stop": "identify",
      "stopLabel": "01 · Identify",
      "method": "POST",
      "path": "/api/v2/patients/lookup",
      "liftedFrom": null,
      "summary": "Resolve an identifier pair to one unique_patient_id, with masked details to confirm the human.",
      "keep": "unique_patient_id",
      "requiresFacilityHeaders": true,
      "planned": null,
      "reference": null
    },
    {
      "id": "registry.practitioners",
      "stop": "identify",
      "stopLabel": "01 · Identify",
      "method": "GET",
      "path": "/api/v1/professionals?identification_number={{practitioner_license}}&identification_type=registration_number&regulator=KMPDC",
      "liftedFrom": null,
      "summary": "Health worker registry — one practitioner, with a licence verdict you do not have to derive.",
      "keep": "licence.status",
      "requiresFacilityHeaders": true,
      "planned": null,
      "reference": null
    },
    {
      "id": "covers.list",
      "stop": "entitle",
      "stopLabel": "02 · Verify cover",
      "method": "GET",
      "path": "/api/v2/patients/{{unique_patient_id}}/covers",
      "liftedFrom": null,
      "summary": "Every cover usable by this member at this facility.",
      "keep": "cover_id",
      "requiresFacilityHeaders": true,
      "planned": null,
      "reference": null
    },
    {
      "id": "covers.select",
      "stop": "entitle",
      "stopLabel": "02 · Verify cover",
      "method": "POST",
      "path": "/api/v2/patients/{{unique_patient_id}}/covers/select",
      "liftedFrom": null,
      "summary": "Freeze a cover onto this encounter.",
      "keep": "selection_ref",
      "requiresFacilityHeaders": true,
      "planned": null,
      "reference": null
    },
    {
      "id": "benefits.tree",
      "stop": "entitle",
      "stopLabel": "02 · Verify cover",
      "method": "GET",
      "path": "/api/v2/patients/{{unique_patient_id}}/eligibility/{{selection_ref}}/benefits",
      "liftedFrom": null,
      "summary": "What the selected cover pays for. Call it with no parent_code for the top level, then pass the code you chose to descend one level, and repeat until nothing comes back.",
      "keep": "benefit_code",
      "requiresFacilityHeaders": true,
      "planned": null,
      "reference": null
    },
    {
      "id": "authentications.initiate",
      "stop": "consent",
      "stopLabel": "03 · Consent",
      "method": "POST",
      "path": "/api/v2/patients/{{unique_patient_id}}/authentications",
      "liftedFrom": null,
      "summary": "Ask for an authentication. The rail decides and executes the factor; you get a resource back, and a URL to embed when the factor is one the member has to be present for.",
      "keep": "authentication_id, collection.url",
      "requiresFacilityHeaders": true,
      "planned": null,
      "reference": null
    },
    {
      "id": "authentications.get",
      "stop": "consent",
      "stopLabel": "03 · Consent",
      "method": "GET",
      "path": "/api/v2/patients/{{unique_patient_id}}/authentications/{{authentication_id}}",
      "liftedFrom": null,
      "summary": "Read the authentication. Poll this as the safety net; the callback is the primary path.",
      "keep": "status, expires_at",
      "requiresFacilityHeaders": true,
      "planned": null,
      "reference": null
    },
    {
      "id": "consent.otp.send",
      "stop": "consent",
      "stopLabel": "03 · Consent",
      "method": "POST",
      "path": "/api/v1/ui/consent/otp/send",
      "liftedFrom": null,
      "summary": "Send the passcode for the launched authentication. Part of the hosted surface: a form post that answers with an HTML fragment, not JSON. Every field is required — the surface re-runs the consent decision on each swap, so the launch context travels with each post.",
      "keep": "the re-rendered verify slot",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "consent.otp.verify",
      "stop": "consent",
      "stopLabel": "03 · Consent",
      "method": "POST",
      "path": "/api/v1/ui/consent/otp/verify",
      "liftedFrom": null,
      "summary": "Check the passcode the member read back. Answers with the receipt fragment on success, and with the executor's own message on a refusal.",
      "keep": "the receipt fragment",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "visit.open",
      "stop": "visit",
      "stopLabel": "04 · Visit",
      "method": "POST",
      "path": "/api/v2/visits",
      "liftedFrom": null,
      "summary": "Open a visit — an encounter and its account, in one atomic write. No payer is called; a visit with no service_lines is purely clinical.",
      "keep": "visit_ref",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "serviceline.add",
      "stop": "visit",
      "stopLabel": "04 · Visit",
      "method": "POST",
      "path": "/api/v2/visits/{{visit_ref}}/service-lines",
      "liftedFrom": null,
      "summary": "Authorise a cover for a named intervention — the authorization unit. Payer-first: pending, then authorized or refused.",
      "keep": "service_line_ref",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "practitioner.add",
      "stop": "visit",
      "stopLabel": "04 · Visit",
      "method": "POST",
      "path": "/api/v2/visits/{{visit_ref}}/practitioners",
      "liftedFrom": null,
      "summary": "Record a practitioner on the visit, validated against the Health Worker Registry under its regulator before it is stored.",
      "keep": "practitioner_ref",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "diagnosis.search",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "GET",
      "path": "/api/v2/clinical/diagnoses?version=serving&q={{diagnosis_query}}",
      "liftedFrom": null,
      "summary": "Search ICD-11 for a codable diagnosis. The picker is fetched, never typed.",
      "keep": "codes[].code",
      "requiresFacilityHeaders": true,
      "planned": "Not registered. The live coded-list surface is /api/v1/terminology — /concepts, /concepts/{concept_id} and /value-sets — which is where an ICD-11 search will resolve from.",
      "reference": "/terminology-api"
    },
    {
      "id": "diagnosis.record",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "POST",
      "path": "/api/v2/visits/{{visit_ref}}/diagnoses",
      "liftedFrom": null,
      "summary": "Record a diagnosis on the visit's clinical record — a Condition on the encounter. A clinical fact first; no cover appears here.",
      "keep": "diagnosis_ref",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "diagnosis.list",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "GET",
      "path": "/api/v1/visits/{{visit_id}}/diagnoses",
      "liftedFrom": null,
      "summary": "Every diagnosis on this visit, and which intervention each one supports.",
      "keep": "diagnoses[].diagnosis_id",
      "requiresFacilityHeaders": false,
      "planned": "No diagnosis routes under a v1 visit. Writing one is live at POST /api/v2/visits/{visit_ref}/diagnoses; reading them back and withdrawing one are not.",
      "reference": null
    },
    {
      "id": "diagnosis.remove",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "DELETE",
      "path": "/api/v1/visits/{{visit_id}}/diagnoses/{{diagnosis_id}}",
      "liftedFrom": null,
      "summary": "Withdraw a diagnosis recorded in error. Refused once the claim is submitted.",
      "keep": "status",
      "requiresFacilityHeaders": false,
      "planned": "No diagnosis routes under a v1 visit. The nearest registered withdrawal is PATCH /api/v1/claims/diagnoses, which acts on a claim rather than on a visit.",
      "reference": null
    },
    {
      "id": "clinical.contribute",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "POST",
      "path": "/api/v1/visits/{{visit_id}}/clinical",
      "liftedFrom": null,
      "summary": "Contribute the encounter to the shared health record as a FHIR bundle.",
      "keep": "bundle_id",
      "requiresFacilityHeaders": false,
      "planned": "There is no /clinical child under a visit, and the registered visits group is v2, not v1. The nearest live calls are POST /api/v2/visits/{visit_ref}/diagnoses and the /api/v1/shr group — neither is a drop-in.",
      "reference": null
    },
    {
      "id": "clinical.read",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "GET",
      "path": "/api/v1/visits/{{visit_id}}/clinical",
      "liftedFrom": null,
      "summary": "Read back what this visit has written — the encounter and every resource under it.",
      "keep": "resources[].id",
      "requiresFacilityHeaders": false,
      "planned": "Same route as clinical.contribute, and equally unregistered. GET /api/v2/visits/{visit_ref}/documents reads what is attached to a visit; it is not a clinical read.",
      "reference": null
    },
    {
      "id": "episodes.list",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "GET",
      "path": "/api/v1/clinical/episodes-of-care",
      "liftedFrom": null,
      "summary": "The episodes of care this patient has open — the thread visits hang from.",
      "keep": "episode_id",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "episodes.open",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "POST",
      "path": "/api/v1/clinical/episodes-of-care",
      "liftedFrom": null,
      "summary": "Open an episode, or attach this visit to one that is already running.",
      "keep": "episode_id",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "orders.create",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "POST",
      "path": "/api/v1/visits/{{visit_id}}/orders",
      "liftedFrom": null,
      "summary": "Order a lab, an image or a procedure. Routed to the performer, whether or not it is you.",
      "keep": "order_id",
      "requiresFacilityHeaders": false,
      "planned": "No /orders prefix exists under either version, and no orders domain in the service.",
      "reference": null
    },
    {
      "id": "orders.inbox",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "GET",
      "path": "/api/v1/orders?performer_facility={{facility_code}}&status=routed",
      "liftedFrom": null,
      "summary": "Orders routed to this facility from anywhere on the rail — your work queue.",
      "keep": "orders[].order_id",
      "requiresFacilityHeaders": false,
      "planned": "No /orders prefix exists under either version.",
      "reference": null
    },
    {
      "id": "orders.result",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "POST",
      "path": "/api/v1/orders/{{order_id}}/results",
      "liftedFrom": null,
      "summary": "Return the result against the order. It reaches the requester without a second integration.",
      "keep": "result_ref",
      "requiresFacilityHeaders": false,
      "planned": "No /orders prefix exists under either version.",
      "reference": null
    },
    {
      "id": "prescriptions.create",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "POST",
      "path": "/api/v1/prescriptions",
      "liftedFrom": null,
      "summary": "Prescribe. Routed to the pharmacy the patient chooses, which may not be yours.",
      "keep": "prescription_id",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "prescriptions.inbox",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "GET",
      "path": "/api/v1/prescriptions",
      "liftedFrom": null,
      "summary": "Prescriptions routed to this pharmacy, written anywhere. Nothing is carried in on paper.",
      "keep": "prescriptions[].prescription_id",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "prescriptions.dispense",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "POST",
      "path": "/api/v1/prescriptions/dispense",
      "liftedFrom": null,
      "summary": "Record what was actually handed over, including a substitution or a partial fill.",
      "keep": "dispense_id",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "prescriptions.doctors.remove",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "DELETE",
      "path": "/api/v1/prescriptions/doctors",
      "liftedFrom": null,
      "summary": "Remove a doctor from a prescription recorded against the wrong prescriber.",
      "keep": "status",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "documents.generate",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "POST",
      "path": "/api/v1/visits/{{visit_id}}/documents/generate",
      "liftedFrom": null,
      "summary": "Generate the documents this claim requires from the clinical data already recorded.",
      "keep": "documents[].document_id",
      "requiresFacilityHeaders": false,
      "planned": "No document routes under a visit. Rendering is live at a different address: POST /api/v1/clinical/document-bundles/{id}/pdf renders a bundle, and POST /api/v1/clinical/html-to-pdf converts HTML you supply. Neither generates a document set from a visit's clinical data.",
      "reference": null
    },
    {
      "id": "documents.render",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "GET",
      "path": "/api/v1/visits/{{visit_id}}/documents/{{document_type}}/render?format=html",
      "liftedFrom": null,
      "summary": "Render a document on demand — HTML to show on screen, PDF to hand over or sign.",
      "keep": "url",
      "requiresFacilityHeaders": false,
      "planned": "No document routes under a visit. GET /api/v1/clinical/document-bundles/{id}/render is the live renderer, scoped to a bundle rather than to a visit and a document type.",
      "reference": null
    },
    {
      "id": "referrals.create",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "POST",
      "path": "/api/v1/visits/{{visit_id}}/referrals",
      "liftedFrom": null,
      "summary": "Refer onward, carrying the clinical record and the authorisation taken here.",
      "keep": "referral_id",
      "requiresFacilityHeaders": false,
      "planned": "No /referrals prefix exists, and there is no referral surface in the service.",
      "reference": null
    },
    {
      "id": "referrals.inbox",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "GET",
      "path": "/api/v1/referrals?facility_code={{facility_code}}&direction=inbound",
      "liftedFrom": null,
      "summary": "Referrals sent to this facility, with the record and the authorisation already attached.",
      "keep": "referrals[].referral_id",
      "requiresFacilityHeaders": false,
      "planned": "No /referrals prefix exists.",
      "reference": null
    },
    {
      "id": "referrals.accept",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "POST",
      "path": "/api/v1/referrals/{{referral_id}}/accept",
      "liftedFrom": null,
      "summary": "Accept or decline a referral, and open the receiving visit against the same authorisation.",
      "keep": "visit_id",
      "requiresFacilityHeaders": false,
      "planned": "No /referrals prefix exists.",
      "reference": null
    },
    {
      "id": "samples.send",
      "stop": "treat",
      "stopLabel": "05 · Treat",
      "method": "POST",
      "path": "/api/v1/referrals/{{referral_id}}/samples",
      "liftedFrom": null,
      "summary": "Send a specimen to the hub, tracked against the order that asked for it.",
      "keep": "sample_id",
      "requiresFacilityHeaders": false,
      "planned": "Hangs off the unregistered /referrals prefix.",
      "reference": null
    },
    {
      "id": "preauth.submit",
      "stop": "preauth",
      "stopLabel": "06 · Preauthorize",
      "method": "POST",
      "path": "/api/v1/preauths",
      "liftedFrom": null,
      "summary": "Submit a preauthorisation for approval.",
      "keep": "reference",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "preauth.poll",
      "stop": "preauth",
      "stopLabel": "06 · Preauthorize",
      "method": "GET",
      "path": "/api/v1/preauths?preauth_reference={{preauth_reference}}",
      "liftedFrom": null,
      "summary": "Poll for the decision. Identical body to the callback.",
      "keep": "authorization_code",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "billline.add",
      "stop": "bill",
      "stopLabel": "07 · Bill",
      "method": "POST",
      "path": "/api/v2/visits/{{visit_ref}}/bill-lines",
      "liftedFrom": null,
      "summary": "Charge under an authorized service line — payer-first. The payer answers with the covered amount and the patient's copay; a line with no service_line_ref is self pay.",
      "keep": "bill_line_ref",
      "requiresFacilityHeaders": false,
      "planned": null,
      "reference": null
    },
    {
      "id": "documents.attach",
      "stop": "bill",
      "stopLabel": "07 · Bill",
      "method": "POST",
      "path": "/api/v1/visits/{{visit_id}}/documents",
      "liftedFrom": null,
      "summary": "Attach a required document against the visit.",
      "keep": "document_id",
      "requiresFacilityHeaders": false,
      "planned": "No route attaches a document to a visit. GET /api/v2/visits/{visit_ref}/documents lists what is attached, and POST /api/v1/clinical/documents/import brings a clinical document in.",
      "reference": null
    },
    {
      "id": "level.change",
      "stop": "bill",
      "stopLabel": "07 · Bill",
      "method": "POST",
      "path": "/api/v1/visits/{{visit_id}}/level-changes",
      "liftedFrom": null,
      "summary": "Retire a per-diem line and start a new one at a different level.",
      "keep": "new_line_id",
      "requiresFacilityHeaders": false,
      "planned": "No /level-changes route is registered.",
      "reference": null
    },
    {
      "id": "claim.preflight",
      "stop": "submit",
      "stopLabel": "08 · Submit",
      "method": "POST",
      "path": "/api/v1/visits/{{visit_id}}/claim/preflight",
      "liftedFrom": null,
      "summary": "Run every gate and return all failures at once.",
      "keep": "reasons[]",
      "requiresFacilityHeaders": false,
      "planned": "Not registered on this path. The registered preflight is POST /api/v2/visits/{visit_ref}/preauths/preflight, which is a preauth check rather than a claim one.",
      "reference": null
    },
    {
      "id": "claim.close",
      "stop": "submit",
      "stopLabel": "08 · Submit",
      "method": "POST",
      "path": "/api/v1/visits/{{visit_id}}/claim/close",
      "liftedFrom": null,
      "summary": "Close the visit and submit. Idempotent on external_id.",
      "keep": "claim_id",
      "requiresFacilityHeaders": false,
      "planned": "Not registered on this path. The nearest registered routes are POST /api/v1/claims/close and POST /api/v1/visits/{visit_id}/close.",
      "reference": null
    },
    {
      "id": "remittances.poll",
      "stop": "reconcile",
      "stopLabel": "09 · Reconcile",
      "method": "GET",
      "path": "/api/v1/remittances?since={{since}}",
      "liftedFrom": null,
      "summary": "Paginated remittances since a timestamp.",
      "keep": "remittance_id",
      "requiresFacilityHeaders": false,
      "planned": "No /remittances route is registered.",
      "reference": null
    }
  ]
}