{"service":"opendoc-protocol","version":"1.0.0-headless","documentation":"https://docs.opendoc.com","openapi":"/protocol/openapi.json","agent_self_serve":{"sandbox_ready":true,"live_ready":false,"signup":"POST /developers/signup — returns a sandbox API key instantly (no approval)","sandbox":"sandbox keys transact against a synthetic provider with simulated (non-live) payments; no real money, no real PHI","how_to_go_live":"request a live key from OpenDoc; workforce-granted only","how_agents_get_authority":"a patient-granted agent token for real transactions (browser grant ceremony); see AGENT_HEADLESS_BOOTSTRAP.md","contact":"https://docs.opendoc.com"},"rate_limits":{"enforced":"per agent-token id (or source IP for public discovery)","on_limit":{"status":429,"error_code":"rate_limited"},"budget_introspection":"GET /agent-tokens/me (effectiveRemainingCents)"},"capabilities":{"mcp":true,"events":{"sse":true,"webhooks":true},"transaction_state_machine":"S0-S8","identity_assurance_levels":["IA0","IA1","IA2"],"consent_layers":2,"cash_price_invariant":true,"sure_price":true,"anti_kickback_enforcement":true,"mass_revocation":true,"concentration_ceiling":0.25,"attenuated_delegation":true,"simulate":true,"signed_price_lock":true,"signed_receipt":true,"first_real_hold_release_pilot":{"enabled":true,"contract_path":"/agent/pilots/first-real-hold-release/contract","live_call_requires_workforce_operator":true,"live_hold_cap":1,"commit_payment_cancel_authority":"not_granted"},"first_real_hold_release_execution":{"enabled":true,"contract_path":"/agent/pilots/first-real-hold-release/execution/contract","dry_run_path":"POST /agent/pilots/first-real-hold-release/execute/dry-run","confirm_path":"POST /agent/pilots/first-real-hold-release/execute/confirm","execute_path":"POST /agent/pilots/first-real-hold-release/execute","reports_path":"GET /agent/pilots/first-real-hold-release/:pilotId/execution-reports","readback_path":"GET /agent/pilots/first-real-hold-release/:pilotId/live-lane-readback","requires_promotion_gate_receipt":"opendoc.review_decision_promotion_gate_receipt","requires_operator_confirmation_receipt":"opendoc.first_real_hold_release_operator_confirmation_receipt","promotion_gate_target_lane":"operator_live_lane","command":"pnpm --filter @opendoc/protocol proof:first-real-hold-release-execution","consumes":["opendoc.review_decision_promotion_gate_receipt","opendoc.staging_ceremony_execution_report"],"success_state":"first_real_hold_released","live_hold_cap":1,"live_hold_cap_ledger_enforced":true,"operator_confirmation_max_age_ms":1800000,"binds_staging_report_hash":true,"evidence_signing":{"algorithm":"ES256","jwks_path":"/.well-known/opendoc-protocol/jwks.json"},"release_required":true,"live_call_requires_workforce_operator":true,"produces":"opendoc.first_real_hold_release_execution_report"},"partner_adapter_rehearsal":{"enabled":true,"command":"pnpm --filter @opendoc/protocol proof:partner-adapter-rehearsal","consumes":["opendoc.staging_ceremony_execution_report","partner_adapter_profile","partner_adapter_checklist","synthetic_adapter_sample_set"],"success_state":"rehearsal_passed","live_provider_hold_attempted":false,"produces":"opendoc.partner_adapter_rehearsal_report"},"partner_pilot_evidence_room":{"enabled":true,"command":"pnpm --filter @opendoc/protocol proof:partner-pilot-evidence-room","consumes":["opendoc.staging_ceremony_execution_report","opendoc.partner_adapter_rehearsal_report","opendoc.first_real_hold_release_execution_report","evidence_artifact_refs"],"success_state":"evidence_ready","stores_phi":false,"produces":"opendoc.partner_pilot_evidence_room_report"},"external_partner_review_portal":{"enabled":true,"contract_path":"/agent/pilots/external-partner-review/contract","issue_grant_path":"POST /agent/pilots/external-partner-review/grants","review_session_path":"GET /agent/pilots/external-partner-review/session","revoke_grant_path":"POST /agent/pilots/external-partner-review/grants/:reviewGrantId/revoke","notify_reviewer_path":"POST /agent/pilots/external-partner-review/grants/:reviewGrantId/notifications","notification_ledger_path":"GET /agent/pilots/external-partner-review/grants/:reviewGrantId/notifications","record_decision_path":"POST /agent/pilots/external-partner-review/decisions","decision_ledger_path":"GET /agent/pilots/external-partner-review/:pilotId/decisions","command":"pnpm --filter @opendoc/protocol proof:external-partner-review-portal","consumes":["opendoc.partner_pilot_evidence_room_report","external_review_grant","reviewer_acknowledgements"],"success_state":"review_recorded","review_grant_transport":"opaque_bearer_token_hash_stored","execution_authority_granted":false,"produces":"opendoc.external_partner_review_receipt"},"review_decision_promotion_gate":{"enabled":true,"contract_path":"/agent/pilots/external-partner-review/promotion-gate/contract","evaluate_path":"POST /agent/pilots/external-partner-review/promotion-gate/evaluate","receipts_path":"GET /agent/pilots/external-partner-review/promotion-gate/:pilotId/receipts","command":"pnpm --filter @opendoc/protocol proof:review-decision-promotion-gate","api_command":"pnpm --filter @opendoc/protocol proof:review-decision-promotion-gate-api","consumes":"opendoc.external_partner_review_receipt","success_state":"promotion_ready","blocked_on_states":["review_required","no_go"],"target_lanes":["partner_pilot_expansion","operator_live_lane","first_booking_commit_lane"],"grants_live_authority":false,"grants_booking_authority":false,"grants_payment_authority":false,"grants_cancel_authority":false,"grants_autonomous_expansion":false,"persists_receipts":true,"produces":"opendoc.review_decision_promotion_gate_receipt"},"live_adapter_test_slot_ceremony":{"enabled":true,"contract_path":"/agent/pilots/live-adapter-test-slot-ceremony/contract","live_provider_hold_allowed":false,"verifies":["credential_refs","adapter_health","test_slot","migration_readiness","dry_run_refs"]},"staging_ceremony_execution":{"enabled":true,"command":"pnpm --filter @opendoc/protocol proof:staging-ceremony-execution","success_state":"ceremony_ready","live_provider_hold_attempted":false,"produces":"opendoc.staging_ceremony_execution_report"},"jwks":"/.well-known/opendoc-protocol/jwks.json"},"auth":{"oidc":{"scheme":"Bearer JWT","status":"durable_identity_input","documentation":"Keycloak or another approved on-prem OIDC provider authenticates identity only; OpenDoc protocol authorization remains database-owned."},"agent_token":{"scheme":"Bearer","grant_path":"POST /agent-tokens","documentation":"Patient grants a scoped token via the marketplace UI or API. Agents may mint attenuated child tokens via POST /agent-tokens/children."}},"events":{"types":["transaction.state_changed","transaction.escrowed","transaction.service_completed","transaction.funds_released","transaction.disputed","provider.availability_changed","provider.price_changed","provider.trust_state_changed","health_key.state_changed","receipt.finalized","market.threshold_reached","agent_ecosystem.revoked"],"sse_path":"/events","webhook_path":"/event-subscriptions","signature_header":"x-opendoc-signature","signature_algorithm":"HMAC-SHA256-hex"},"permissions":["search","BOOK","CANCEL","READ_BOOKINGS","READ_TRANSACTIONS","READ_RECEIPTS","READ_PROFILE","READ_CONSENT","READ_HEALTH_KEY","pay","manage_catalog","manage_availability","view_bookings","submit_pos","manage_ehr_provider_link"],"consents":{"layer_1":[{"key":"data_tier_2","description":"Read clinical-detail data tier"},{"key":"data_tier_3","description":"Read full data tier (PHI breadth)"}],"layer_2":[{"key":"BOOK","description":"Allow agents to complete bookings"},{"key":"CANCEL","description":"Allow agents to cancel bookings"},{"key":"GRANT_AGENT_TOKEN","description":"Allow granting agent tokens"},{"key":"SHARE_RECEIPT_INSURANCE","description":"Allow exporting insurance-format receipts"},{"key":"SHARE_PROJECTION","description":"Allow sharing visit projection"},{"key":"DISPUTE","description":"Allow filing disputes on patient's behalf"},{"key":"SHARE_RECORDS","description":"Allow minting a patient→recipient record-share access grant"},{"key":"LINK_EMPLOYER_BENEFIT","description":"Link this account to an employer funding benefit (scoped per employer)"}]},"error_shape":{"example":{"error":{"code":"authentication_required","message":"agent token required","correlationId":"abc123-..."}},"codes":["authentication_required","forbidden","not_found","conflict","unprocessable_entity","rate_limited","payment_required","internal_error"]},"tools":[{"name":"search","toolset":"discovery","method":"GET","path":"/search","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"CRE-routed semantic search across providers + HSOs. Returns individual clinicians by default; pass entityType=organization|all to include practice/organization NPIs."},{"name":"clinical_route","toolset":"discovery","method":"GET","path":"/clinical-route","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"Natural-language clinical routing: symptom/diagnosis → service lens → eligible specialists, with deterministic ER/urgent safety intercepts."},{"name":"care_lane_care_plan","toolset":"discovery","method":"GET","path":"/search/care-plan","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"Read-only care-lane care-plan preview: diagnosis/specialty/procedure → provider search, symptom → guided intake, safety → guidance before provider ranking."},{"name":"care_lane_providers","toolset":"discovery","method":"GET","path":"/search/care-lane-providers","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"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."},{"name":"text_concierge_turn","toolset":"discovery","method":"POST","path":"/text-concierge/turn","authority":"public","authRequired":"none","sideEffect":"simulate","signing":"none","description":"Run one OpenDoc Text Concierge turn: model-assisted conversation interpretation with guarded safety/action execution, provider search, office-request collection, and secure booking handoff."},{"name":"list_hsos","toolset":"discovery","method":"GET","path":"/hsos","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"Catalog list with min-price aggregate."},{"name":"get_hso","toolset":"discovery","method":"GET","path":"/hsos/:slug","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"HSO detail + every provider offering it."},{"name":"list_providers","toolset":"discovery","method":"GET","path":"/providers","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"Active providers with text search."},{"name":"get_provider","toolset":"discovery","method":"GET","path":"/providers/:id","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"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}."},{"name":"check_availability","toolset":"discovery","method":"GET","path":"/providers/:id/availability","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"Open availability slots in a window. :id accepts the provider UUID or a 10-digit NPI."},{"name":"get_npi_profile","toolset":"discovery","method":"GET","path":"/npi/:npi","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"Public directory profile + activation state for ANY 10-digit NPI (9M+ providers), onboarded or not. The fallback pivot when get_provider 404s."},{"name":"list_offers","toolset":"discovery","method":"GET","path":"/offers","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"Flat (provider × HSO × SCP) rate-card list."},{"name":"get_sure_price","toolset":"discovery","method":"GET","path":"/sure-price","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"Machine-verifiable ceiling guarantee per HSO × geo × payer."},{"name":"get_registry_prices","toolset":"discovery","method":"GET","path":"/registry/prices","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"The Price Registry (ADR 0130): committed, escrow-backed, all-in cash prices per (service × market) cell with settlement-proof metadata and freshness. Committed prices only — estimates and phone-reported quotes are deliberately excluded. Filter by ?service={hso-slug} and/or ?market=us-{state}[-{city-slug}]."},{"name":"get_registry_summary","toolset":"discovery","method":"GET","path":"/registry/summary","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"Per-market real-price density for the Price Registry: how many registry-panel services have a committed price in each market. The registry publishes its own coverage scoreboard."},{"name":"get_provider_sitemap_feed","toolset":"discovery","method":"GET","path":"/sitemap/providers","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"Bulk provider directory feed (the crawl-surface contract, ADR 0099): identity, geo, credentials, and — for activated providers — posted bookable all-in cash services. One response, 10-min cache."},{"name":"get_price_benchmark","toolset":"discovery","method":"GET","path":"/price-benchmark","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"Factual Medicare (CMS PFS non-facility) reference amount for a HCPCS/CPT code — an attributed, dated benchmark, never an OpenDoc price. 404s when unseeded rather than inventing a number."},{"name":"get_trust","toolset":"discovery","method":"GET","path":"/trust/scp/:scpId","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"8-domain reliability state for an SCP."},{"name":"list_specialties","toolset":"discovery","method":"GET","path":"/specialties","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"Distinct specialties with provider counts."},{"name":"protocol_jwks","toolset":"discovery","method":"GET","path":"/.well-known/opendoc-protocol/jwks.json","authority":"public","authRequired":"none","sideEffect":"read","signing":"none","description":"Published ES256 public keys for verifying signed price-locks and receipts offline (Doctrine §3)."},{"name":"declare_intent","toolset":"transaction","method":"POST","path":"/transactions/declare-intent","authority":"patient","authRequired":"identity_session","permission":"BOOK","sideEffect":"write","signing":"none","description":"S0 → S1. Declare booking intent."},{"name":"authorize","toolset":"transaction","method":"POST","path":"/transactions/:id/authorize","authority":"patient","authRequired":"identity_session","permission":"BOOK","sideEffect":"write","signing":"price_lock","description":"S1 → S2. HSO Instance born; price locked. Returns a signed price-lock."},{"name":"simulate","toolset":"transaction","method":"POST","path":"/transactions/:id/simulate","authority":"patient","authRequired":"identity_session","permission":"READ_TRANSACTIONS","sideEffect":"simulate","signing":"price_lock","description":"Side-effect-free preview of authorize/commit: returns the exact signed price-lock and obligation with zero writes (Doctrine §2)."},{"name":"accept_terms","toolset":"transaction","method":"POST","path":"/transactions/:id/accept-terms","authority":"patient","authRequired":"identity_session","permission":"BOOK","sideEffect":"write","signing":"none","description":"S2 → S3. Bind payment method."},{"name":"commit","toolset":"transaction","method":"POST","path":"/transactions/:id/commit","authority":"patient","authRequired":"identity_session","permission":"BOOK","sideEffect":"write","signing":"none","description":"S3 → S4 atomic commit."},{"name":"get_transaction","toolset":"transaction","method":"GET","path":"/transactions/:id","authority":"patient","authRequired":"identity_session","permission":"READ_TRANSACTIONS","sideEffect":"read","signing":"none","description":"Read current state."},{"name":"cancel_booking","toolset":"transaction","method":"POST","path":"/bookings/:id/cancel","authority":"patient","authRequired":"identity_session","permission":"CANCEL","sideEffect":"write","signing":"none","description":"Cancel before fulfillment."},{"name":"begin_save_payment_method","toolset":"patient","method":"POST","path":"/me/payment-methods/setup-intent","authority":"patient","authRequired":"identity_session","sideEffect":"write","signing":"none","description":"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."},{"name":"get_payment_method","toolset":"patient","method":"GET","path":"/me/payment-methods","authority":"patient","authRequired":"identity_session","permission":"READ_PROFILE","sideEffect":"read","signing":"none","description":"Saved-card summary (hasSavedPaymentMethod + display fields only). Agent-readable so an agent can check for a card on file before promising to transact; chargeable ids are never returned."},{"name":"remove_payment_method","toolset":"patient","method":"DELETE","path":"/me/payment-methods","authority":"patient","authRequired":"identity_session","sideEffect":"write","signing":"none","description":"Remove the saved card (detach + clear default). Human-only."},{"name":"open_dispute","toolset":"transaction","method":"POST","path":"/me/bookings/:id/dispute","authority":"patient","authRequired":"identity_session","sideEffect":"write","signing":"none","description":"Patient asserts \"the service did not happen as defined\" on their own release-pending booking; the provider's held funds are frozen (remittance blocked — dispute blocks both release paths). Human-only: agent tokens are rejected by design. Binary outcome downstream: full refund (the provider's non-delivery obligation) or full release (the provider delivered)."},{"name":"resolve_dispute","toolset":"transaction","method":"POST","path":"/admin/bookings/:id/dispute/resolve","authority":"workforce","authRequired":"workforce","permission":"workforce.admin","sideEffect":"write","signing":"none","description":"Workforce-only resolution of an open dispute: full refund (the provider's non-delivery refund obligation, administered by Sherlock as the provider's agent) or full release (the provider met its committed delivery definition), required precedent note. Determined by impartially applying the provider's own Proof-of-Service definition; provider-side actors are excluded so a provider cannot grade its own delivery (ADR 0113)."},{"name":"submit_proof_of_service","toolset":"provider","method":"POST","path":"/admin/bookings/:id/fulfill","authority":"provider","authRequired":"identity_session","permission":"submit_pos","sideEffect":"write","signing":"receipt","description":"Submit proof of service / fulfill a booking; releases escrow and issues the signed receipt."},{"name":"create_offer","toolset":"provider","method":"POST","path":"/offers","authority":"provider","authRequired":"identity_session","permission":"manage_catalog","sideEffect":"write","signing":"none","description":"Create or update a scoped provider/SCP catalog offer."},{"name":"create_health_key","toolset":"patient","method":"POST","path":"/health-keys","authority":"patient","authRequired":"identity_session","sideEffect":"write","signing":"none","description":"Create a Health Key (idempotent)."},{"name":"get_health_key","toolset":"patient","method":"GET","path":"/health-keys/me","authority":"patient","authRequired":"identity_session","permission":"READ_HEALTH_KEY","sideEffect":"read","signing":"none","description":"Read the patient's active Health Key."},{"name":"promote_ia2","toolset":"patient","method":"POST","path":"/health-keys/me/promote-ia2","authority":"patient","authRequired":"identity_session","sideEffect":"write","signing":"none","description":"Promote Health Key to IA2 (transactable)."},{"name":"list_consent","toolset":"patient","method":"GET","path":"/me/consent","authority":"patient","authRequired":"identity_session","permission":"READ_CONSENT","sideEffect":"read","signing":"none","description":"List active Layer 1 + Layer 2 grants."},{"name":"grant_consent","toolset":"patient","method":"POST","path":"/me/consent","authority":"patient","authRequired":"identity_session","sideEffect":"write","signing":"none","description":"Grant a data tier (Layer 1) or action (Layer 2) consent."},{"name":"revoke_consent","toolset":"patient","method":"POST","path":"/me/consent/:id/revoke","authority":"patient","authRequired":"identity_session","sideEffect":"write","signing":"none","description":"Revoke a specific grant."},{"name":"get_my_profile","toolset":"patient","method":"GET","path":"/me/profile","authority":"patient","authRequired":"identity_session","permission":"READ_PROFILE","sideEffect":"read","signing":"none","description":"Read patient self-profile."},{"name":"update_my_profile","toolset":"patient","method":"PATCH","path":"/me/profile","authority":"patient","authRequired":"identity_session","sideEffect":"write","signing":"none","description":"Patch patient self-profile."},{"name":"list_my_bookings","toolset":"patient","method":"GET","path":"/me/bookings","authority":"patient","authRequired":"identity_session","permission":"READ_BOOKINGS","sideEffect":"read","signing":"none","description":"Patient's own booking history."},{"name":"list_my_receipts","toolset":"patient","method":"GET","path":"/me/receipts","authority":"patient","authRequired":"identity_session","permission":"READ_RECEIPTS","sideEffect":"read","signing":"none","description":"List receipts (patient view)."},{"name":"get_my_receipt","toolset":"patient","method":"GET","path":"/me/receipts/:id","authority":"patient","authRequired":"identity_session","permission":"READ_RECEIPTS","sideEffect":"read","signing":"receipt","description":"Receipt detail with a signed, offline-verifiable receipt object. format=insurance requires SHARE_RECEIPT_INSURANCE Layer 2 consent."},{"name":"grant_agent_token","toolset":"patient","method":"POST","path":"/agent-tokens","authority":"patient","authRequired":"identity_session","sideEffect":"write","signing":"none","description":"Mint a scoped root agent token (rawToken returned ONCE)."},{"name":"list_agent_tokens","toolset":"patient","method":"GET","path":"/agent-tokens","authority":"patient","authRequired":"identity_session","sideEffect":"read","signing":"none","description":"List the patient's active agent tokens."},{"name":"revoke_agent_token","toolset":"patient","method":"POST","path":"/agent-tokens/:id/revoke","authority":"patient","authRequired":"identity_session","sideEffect":"write","signing":"none","description":"Revoke an agent token; cascades to its entire subtree."},{"name":"mint_child_token","toolset":"delegation","method":"POST","path":"/agent-tokens/children","authority":"patient","authRequired":"agent_token","sideEffect":"write","signing":"none","description":"Mint a strictly-weaker CHILD token from the calling agent token, under enforced attenuation (Doctrine §1)."},{"name":"events_stream","toolset":"events","method":"GET","path":"/events","authority":"system","authRequired":"agent_token","sideEffect":"read","signing":"none","description":"SSE stream of canonical protocol events."},{"name":"create_event_subscription","toolset":"events","method":"POST","path":"/event-subscriptions","authority":"system","authRequired":"agent_token","sideEffect":"write","signing":"none","description":"Register a webhook callback (HMAC-signed)."}]}