{"openapi":"3.1.0","info":{"title":"OpenDoc Protocol API","version":"1.0.0-headless","description":"The cash-pay healthcare transaction protocol. See https://docs.opendoc.com for the full spec."},"servers":[{"url":"https://api.opendoc.com","description":"production"},{"url":"/","description":"this origin"}],"paths":{"/search":{"get":{"operationId":"search","tags":["discovery"],"summary":"CRE-routed semantic search across providers + HSOs. Returns individual clinicians by default; pass entityType=organization|all to include practice/organization NPIs.","x-side-effect":"read","x-signed-output":"none","x-authority":"public","security":[]}},"/clinical-route":{"get":{"operationId":"clinical_route","tags":["discovery"],"summary":"Natural-language clinical routing: symptom/diagnosis → service lens → eligible specialists, with deterministic ER/urgent safety intercepts.","x-side-effect":"read","x-signed-output":"none","x-authority":"public","security":[]}},"/search/care-plan":{"get":{"operationId":"care_lane_care_plan","tags":["discovery"],"summary":"Read-only care-lane care-plan preview: diagnosis/specialty/procedure → provider search, symptom → guided intake, safety → guidance before provider ranking.","x-side-effect":"read","x-signed-output":"none","x-authority":"public","security":[]}},"/search/care-lane-providers":{"get":{"operationId":"care_lane_providers","tags":["discovery"],"summary":"Read-only care-lane provider search: ranks providers against a resolved care lane with explainable match/exclusion reasons (including condition-level scope), gated behind the care-lane provider-search preview flag.","x-side-effect":"read","x-signed-output":"none","x-authority":"public","security":[]}},"/text-concierge/turn":{"post":{"operationId":"text_concierge_turn","tags":["discovery"],"summary":"Run one deterministic OpenDoc Text Concierge turn: patient text -> intent, safety check, service path, top-three options, A/B/C selection, BOOK handoff.","x-side-effect":"simulate","x-signed-output":"none","x-authority":"public","security":[]}},"/hsos":{"get":{"operationId":"list_hsos","tags":["discovery"],"summary":"Catalog list with min-price aggregate.","x-side-effect":"read","x-signed-output":"none","x-authority":"public","security":[]}},"/hsos/{slug}":{"get":{"operationId":"get_hso","tags":["discovery"],"summary":"HSO detail + every provider offering it.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"read","x-signed-output":"none","x-authority":"public","security":[]}},"/providers":{"get":{"operationId":"list_providers","tags":["discovery"],"summary":"Active providers with text search.","x-side-effect":"read","x-signed-output":"none","x-authority":"public","security":[]}},"/providers/{id}":{"get":{"operationId":"get_provider","tags":["discovery"],"summary":"Provider detail + their full rate-card offerings. :id accepts the provider UUID or a 10-digit NPI (the key /search and /clinical-route results carry); an NPI that is not onboarded 404s with a pointer to /npi/{npi}.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"read","x-signed-output":"none","x-authority":"public","security":[]}},"/providers/{id}/availability":{"get":{"operationId":"check_availability","tags":["discovery"],"summary":"Open availability slots in a window. :id accepts the provider UUID or a 10-digit NPI.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"read","x-signed-output":"none","x-authority":"public","security":[]}},"/npi/{npi}":{"get":{"operationId":"get_npi_profile","tags":["discovery"],"summary":"Public directory profile + activation state for ANY 10-digit NPI (9M+ providers), onboarded or not. The fallback pivot when get_provider 404s.","parameters":[{"name":"npi","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"read","x-signed-output":"none","x-authority":"public","security":[]}},"/offers":{"post":{"operationId":"create_offer","tags":["provider"],"summary":"Create or update a scoped provider/SCP catalog offer.","x-side-effect":"write","x-signed-output":"none","x-authority":"provider","security":[{"OidcBearer":[]}]}},"/sure-price":{"get":{"operationId":"get_sure_price","tags":["discovery"],"summary":"Machine-verifiable ceiling guarantee per HSO × geo × payer.","x-side-effect":"read","x-signed-output":"none","x-authority":"public","security":[]}},"/trust/scp/{scpId}":{"get":{"operationId":"get_trust","tags":["discovery"],"summary":"8-domain reliability state for an SCP.","parameters":[{"name":"scpId","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"read","x-signed-output":"none","x-authority":"public","security":[]}},"/specialties":{"get":{"operationId":"list_specialties","tags":["discovery"],"summary":"Distinct specialties with provider counts.","x-side-effect":"read","x-signed-output":"none","x-authority":"public","security":[]}},"/.well-known/opendoc-protocol/jwks.json":{"get":{"operationId":"protocol_jwks","tags":["discovery"],"summary":"Published ES256 public keys for verifying signed price-locks and receipts offline (Doctrine §3).","x-side-effect":"read","x-signed-output":"none","x-authority":"public","security":[]}},"/transactions/declare-intent":{"post":{"operationId":"declare_intent","tags":["transaction"],"summary":"S0 → S1. Declare booking intent.","x-side-effect":"write","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/transactions/{id}/authorize":{"post":{"operationId":"authorize","tags":["transaction"],"summary":"S1 → S2. HSO Instance born; price locked. Returns a signed price-lock.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"write","x-signed-output":"price_lock","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/transactions/{id}/simulate":{"post":{"operationId":"simulate","tags":["transaction"],"summary":"Side-effect-free preview of authorize/commit: returns the exact signed price-lock and obligation with zero writes (Doctrine §2).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"simulate","x-signed-output":"price_lock","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/transactions/{id}/accept-terms":{"post":{"operationId":"accept_terms","tags":["transaction"],"summary":"S2 → S3. Bind payment method.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"write","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/transactions/{id}/commit":{"post":{"operationId":"commit","tags":["transaction"],"summary":"S3 → S4 atomic commit.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"write","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/transactions/{id}":{"get":{"operationId":"get_transaction","tags":["transaction"],"summary":"Read current state.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"read","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/bookings/{id}/cancel":{"post":{"operationId":"cancel_booking","tags":["transaction"],"summary":"Cancel before fulfillment.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"write","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/me/payment-methods/setup-intent":{"post":{"operationId":"begin_save_payment_method","tags":["patient"],"summary":"Begin the save-card ceremony: returns a Stripe SetupIntent clientSecret for Elements. Human-only. Once saved, transactions can pay off-session via accept-terms { useSavedPaymentMethod: true } — the headless payment path.","x-side-effect":"write","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/me/payment-methods":{"delete":{"operationId":"remove_payment_method","tags":["patient"],"summary":"Remove the saved card (detach + clear default). Human-only.","x-side-effect":"write","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/me/bookings/{id}/dispute":{"post":{"operationId":"open_dispute","tags":["transaction"],"summary":"Patient asserts \"the service did not happen as defined\" on their own release-pending booking; escrow freezes immediately (dispute blocks both release paths). Human-only: agent tokens are rejected by design. Binary outcome downstream: full refund or full release.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"write","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/admin/bookings/{id}/dispute/resolve":{"post":{"operationId":"resolve_dispute","tags":["transaction"],"summary":"Workforce-only binary adjudication of an open dispute: full refund or full release, required precedent note. Provider-side actors are excluded by policy (neutrality by construction).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"write","x-signed-output":"none","x-authority":"workforce","security":[{"OidcBearer":[]}]}},"/admin/bookings/{id}/fulfill":{"post":{"operationId":"submit_proof_of_service","tags":["provider"],"summary":"Submit proof of service / fulfill a booking; releases escrow and issues the signed receipt.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"write","x-signed-output":"receipt","x-authority":"provider","security":[{"OidcBearer":[]}]}},"/health-keys":{"post":{"operationId":"create_health_key","tags":["patient"],"summary":"Create a Health Key (idempotent).","x-side-effect":"write","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/health-keys/me":{"get":{"operationId":"get_health_key","tags":["patient"],"summary":"Read the patient's active Health Key.","x-side-effect":"read","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/health-keys/me/promote-ia2":{"post":{"operationId":"promote_ia2","tags":["patient"],"summary":"Promote Health Key to IA2 (transactable).","x-side-effect":"write","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/me/consent":{"post":{"operationId":"grant_consent","tags":["patient"],"summary":"Grant a data tier (Layer 1) or action (Layer 2) consent.","x-side-effect":"write","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/me/consent/{id}/revoke":{"post":{"operationId":"revoke_consent","tags":["patient"],"summary":"Revoke a specific grant.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"write","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/me/profile":{"patch":{"operationId":"update_my_profile","tags":["patient"],"summary":"Patch patient self-profile.","x-side-effect":"write","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/me/bookings":{"get":{"operationId":"list_my_bookings","tags":["patient"],"summary":"Patient's own booking history.","x-side-effect":"read","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/me/receipts":{"get":{"operationId":"list_my_receipts","tags":["patient"],"summary":"List receipts (patient view).","x-side-effect":"read","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/me/receipts/{id}":{"get":{"operationId":"get_my_receipt","tags":["patient"],"summary":"Receipt detail with a signed, offline-verifiable receipt object. format=insurance requires SHARE_RECEIPT_INSURANCE Layer 2 consent.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"read","x-signed-output":"receipt","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/agent-tokens":{"get":{"operationId":"list_agent_tokens","tags":["patient"],"summary":"List the patient's active agent tokens.","x-side-effect":"read","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/agent-tokens/{id}/revoke":{"post":{"operationId":"revoke_agent_token","tags":["patient"],"summary":"Revoke an agent token; cascades to its entire subtree.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-side-effect":"write","x-signed-output":"none","x-authority":"patient","security":[{"OidcBearer":[]}]}},"/agent-tokens/children":{"post":{"operationId":"mint_child_token","tags":["delegation"],"summary":"Mint a strictly-weaker CHILD token from the calling agent token, under enforced attenuation (Doctrine §1).","x-side-effect":"write","x-signed-output":"none","x-authority":"patient","security":[{"AgentToken":[]}]}},"/events":{"get":{"operationId":"events_stream","tags":["events"],"summary":"SSE stream of canonical protocol events.","x-side-effect":"read","x-signed-output":"none","x-authority":"system","security":[{"AgentToken":[]}]}},"/event-subscriptions":{"post":{"operationId":"create_event_subscription","tags":["events"],"summary":"Register a webhook callback (HMAC-signed).","x-side-effect":"write","x-signed-output":"none","x-authority":"system","security":[{"AgentToken":[]}]}}},"components":{"securitySchemes":{"OidcBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"AgentToken":{"type":"http","scheme":"bearer"}}}}