{"openapi":"3.1.0","info":{"title":"TiC Explorer API","description":"**TiC Explorer** — negotiated health-care prices from **Transparency in Coverage** files (every in-network rate a plan pays each\nbilling entity), Original Medicare fee schedules and, as a secondary source, hospitals' own price files (each hospital's\nposted rate per payer/plan as it wrote them, mostly facility charges, and its discounted cash price) — with the billing\nsemantics needed to use them correctly: allowed vs billed vs patient share, global vs 26/TC, office vs facility rates, hospital outpatient APC\ncase rates and packaging, placeholders and percent-of-charges contracts, and per-row provenance.\n\n**Start with** `GET /v1/guide` (billing mechanics, field dictionary, worked examples) and `GET /v1/workflows`.\n\n**Auth:** `Authorization: Bearer <API key>`. Get a key in the console at https://ticexplorer.com/dashboard/keys (self-hosted:\n`python -m api keys create` or `POST /v1/admin/keys`). The MCP endpoint `https://api.ticexplorer.com/mcp` accepts the same API keys\nor OAuth 2.1 access tokens, e.g. `claude mcp add --transport http ticexplorer https://api.ticexplorer.com/mcp`.\n\n**Conventions:** list responses are `{\"data\": [...], \"next_cursor\": ...}` (pass `cursor`); errors are\n`{\"error\": {\"code\", \"message\", \"hint\"}}`; every response has `X-Request-Id`, `X-RateLimit-Limit`,\n`X-RateLimit-Remaining`, `X-RateLimit-Reset`. Responses carry `needs` (missing inputs that change the answer) and\n`next_steps`.","version":"0.3.0"},"servers":[{"url":"/"}],"paths":{"/v1/plans":{"get":{"tags":["plans"],"summary":"Find a health plan","description":"Employer / insurer / plan name / EIN / marketplace plan id → plans, with the `plan_id` used by rates and claims.\n\n**Workflows**\n\nWorkflow `estimate-visit-cost`, step 1/4 `resolve-plan`: Estimate what a visit will cost a person before care, under their plan, at a specific place.\n- Purpose: Resolves the person's plan; one employer can map to several insurers, and the ID card names the one that applies.\n- Next: `find_providers`\n\nWorkflow `check-a-bill`, step 1/3 `resolve-plan`: Check whether a received bill or EOB matches the plan's published negotiated prices.\n- Next: `find_providers`\n\nWorkflow `compare-places`, step 1/3 `resolve-plan`: Compare what the plan pays different nearby providers for the same service.\n- Next: `find_codes`","operationId":"find_plan","security":[{"HTTPBearer":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","description":"Employer, insurer, plan name, EIN or HIOS id","examples":["microsoft premera"],"title":"Q"},"description":"Employer, insurer, plan name, EIN or HIOS id"},{"name":"zip","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Member ZIP (ranks plans in that state first)","title":"Zip"},"description":"Member ZIP (ranks plans in that state first)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":10,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanList"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"}}}},"/v1/plans/{plan_id}":{"get":{"tags":["plans"],"summary":"Get a plan and its rate files","operationId":"get_plan","security":[{"HTTPBearer":[]}],"parameters":[{"name":"plan_id","in":"path","required":true,"schema":{"type":"string","title":"Plan Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanDetail"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"}}}},"/v1/providers":{"get":{"tags":["providers"],"summary":"Resolve a place/clinician into locations, billing entities and hospital ownership","operationId":"find_providers","security":[{"HTTPBearer":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Name or street address, e.g. \"uchealth urgent care\" or \"1635 Aurora Ct\"","title":"Q"},"description":"Name or street address, e.g. \"uchealth urgent care\" or \"1635 Aurora Ct\""},{"name":"zip","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"5-digit ZIP to search near","title":"Zip"},"description":"5-digit ZIP to search near"},{"name":"miles","in":"query","required":false,"schema":{"type":"number","maximum":100,"minimum":0.5,"default":10,"title":"Miles"}},{"name":"npi","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Npi"}},{"name":"tin","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Billing entity tax ID","title":"Tin"},"description":"Billing entity tax ID"},{"name":"plan_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"From find_plan: needed for billing entities (TINs)","title":"Plan Id"},"description":"From find_plan: needed for billing entities (TINs)"},{"name":"codes","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated codes: Medicare billing evidence, or list who near the ZIP bills them when q is empty","title":"Codes"},"description":"Comma-separated codes: Medicare billing evidence, or list who near the ZIP bills them when q is empty"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvidersResult"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"}},"description":"\n\n**Workflows**\n\nWorkflow `estimate-visit-cost`, step 2/4 `resolve-provider`: Estimate what a visit will cost a person before care, under their plan, at a specific place.\n- Purpose: Turns the place into billing entities (TINs), including related entities such as an owning hospital.\n- Call after: `find_plan`\n- Next: `find_codes`\n\nWorkflow `check-a-bill`, step 2/3 `resolve-billing-entity`: Check whether a received bill or EOB matches the plan's published negotiated prices.\n- Purpose: Includes related_entities, since a hospital-owned clinic's labs/imaging are often billed by the hospital.\n- Call after: `find_plan`\n- Next: `price_claim`"}},"/v1/codes":{"get":{"tags":["codes"],"summary":"Find billing codes for a service","operationId":"find_codes","security":[{"HTTPBearer":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","description":"Service in plain words, or one or more codes","examples":["chest x-ray"],"title":"Q"},"description":"Service in plain words, or one or more codes"},{"name":"zip","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ZIP for locality-adjusted Medicare fees","title":"Zip"},"description":"ZIP for locality-adjusted Medicare fees"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":25,"minimum":1,"default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodesResult"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"}},"description":"\n\n**Workflows**\n\nWorkflow `estimate-visit-cost`, step 3/4 `find-codes`: Estimate what a visit will cost a person before care, under their plan, at a specific place.\n- Purpose: Candidate codes for each expected service; `clarify` names details that change the code.\n- Call after: `find_providers`\n- Next: `price_claim`\n\nWorkflow `compare-places`, step 2/3 `find-codes`: Compare what the plan pays different nearby providers for the same service.\n- Call after: `find_plan`\n- Next: `get_rates`\n\nWorkflow `compare-coverage-routes`, step 1/2 `find-codes`: Compare the same services under the person's plan, Original Medicare and hospital cash prices in one call.\n- Purpose: Confirms the codes and returns their facts (hospital status indicator, Medicare fee).\n- Next: `get_rates_batch`\n\nWorkflow `market-analysis`, step 1/4 `find-codes`: Aggregate rate statistics for services across insurers and all providers in an area (benchmarking, research, negotiation prep, exports).\n- Purpose: Codes for each service, from the code dictionary.\n- Next: `estimate_market_analysis`"}},"/v1/rates":{"post":{"tags":["rates"],"summary":"Negotiated rates for codes near a place","description":"Coverage × codes × providers-or-area → self-describing rate rows + summary. First use of a plan's rate files\nindexes them just in time (up to `wait_seconds`); later calls are fast.\n\n**Workflows**\n\nWorkflow `compare-places`, step 3/3 `rates`: Compare what the plan pays different nearby providers for the same service.\n- Purpose: Rows are comparable within the same billing component and place of service; a global rate already includes 26 + TC.\n- Call after: `find_codes`","operationId":"get_rates","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RatesRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RatesResult"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/rates/batch":{"post":{"tags":["rates"],"summary":"Several rate queries in one call","description":"Up to 10 `get_rates` requests (different coverages, areas, entities or code sets) in one call.\n\n**Workflows**\n\nWorkflow `compare-coverage-routes`, step 2/2 `rates-by-route`: Compare the same services under the person's plan, Original Medicare and hospital cash prices in one call.\n- Purpose: One request per coverage route (plan, medicare, hospital cash), each with a label.\n- Call after: `find_codes`","operationId":"get_rates_batch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RatesBatchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RatesBatchResult"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/claims/price":{"post":{"tags":["claims"],"summary":"Price or reconcile a whole claim","description":"Many claim lines at one or more candidate billing entities → the rate each entity would be paid per line (APC\ncase rates, packaging, office vs facility), totals, and — with `claim_allowed_total` — a reconciliation verdict.\n\n**Workflows**\n\nWorkflow `estimate-visit-cost`, step 4/4 `price-visit`: Estimate what a visit will cost a person before care, under their plan, at a specific place.\n- Purpose: Prices all expected lines at the candidate billing entities for the given place of service.\n- Call after: `find_codes`\n\nWorkflow `check-a-bill`, step 3/3 `reconcile`: Check whether a received bill or EOB matches the plan's published negotiated prices.\n- Purpose: Reconciles the claim at the billing entity and related entities; hospital bills are place_of_service hospital_outpatient.\n- Call after: `find_providers`","operationId":"price_claim","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimResult"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/analytics/estimate":{"post":{"tags":["analytics"],"summary":"Preflight a market analysis: files, time, price","description":"Resolve codes x geography x payers to the rate files that must be read (warm = already indexed; cold = indexed just in\ntime), with the estimated time and price. Nothing is started.\n\n**Workflows**\n\nWorkflow `market-analysis`, step 2/4 `estimate`: Aggregate rate statistics for services across insurers and all providers in an area (benchmarking, research, negotiation prep, exports).\n- Purpose: Preflight - files needed (warm vs cold), estimated seconds and usage charge, limit violations (a narrower scope removes them).\n- Call after: `find_codes`\n- Next: `start_market_analysis`","operationId":"estimate_market_analysis","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Open"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/analytics/jobs":{"post":{"tags":["analytics"],"summary":"Start a market analysis (async job)","description":"Starts the analysis and returns the job (poll GET /v1/analytics/jobs/{job_id}). 409 price_confirmation_required when the\nhigh estimate exceeds max_price_usd (default $1); 402 when the prepaid balance cannot hold the high estimate (only the\nactual price is charged when the job ends; the rest of the hold goes back); 429 when the account\nalready has two analyses running and two queued.\n\n**Workflows**\n\nWorkflow `market-analysis`, step 3/4 `start`: Aggregate rate statistics for services across insurers and all providers in an area (benchmarking, research, negotiation prep, exports).\n- Purpose: Starts the job with the same inputs (409 price_confirmation_required = high estimate above max_price_usd).\n- Call after: `estimate_market_analysis`\n- Next: `get_market_analysis`","operationId":"start_market_analysis","security":[{"HTTPBearer":[]}],"parameters":[{"name":"wait_seconds","in":"query","required":false,"schema":{"type":"integer","maximum":120,"minimum":0,"description":"Wait up to this long for the job to finish before answering (0 = return the job at once).","default":0,"title":"Wait Seconds"},"description":"Wait up to this long for the job to finish before answering (0 = return the job at once)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Open"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Conflict"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Gone"}}},"get":{"tags":["analytics"],"summary":"This account's analyses (this server process)","operationId":"list_market_analyses","security":[{"HTTPBearer":[]}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Open"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"}}}},"/v1/analytics/jobs/{job_id}":{"get":{"tags":["analytics"],"summary":"Progress and (partial) results of a market analysis","operationId":"get_market_analysis","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"wait_seconds","in":"query","required":false,"schema":{"type":"integer","maximum":120,"minimum":0,"description":"Long-poll: wait up to this long for the job to finish.","default":0,"title":"Wait Seconds"},"description":"Long-poll: wait up to this long for the job to finish."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Open"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Gone"}},"description":"\n\n**Workflows**\n\nWorkflow `market-analysis`, step 4/4 `results`: Aggregate rate statistics for services across insurers and all providers in an area (benchmarking, research, negotiation prep, exports).\n- Purpose: Polls until status is done or partial; medians and p10-p90 per group, exclusions and coverage.gaps.\n- Call after: `start_market_analysis`"},"delete":{"tags":["analytics"],"summary":"Cancel a market analysis (results read so far are kept)","operationId":"cancel_market_analysis","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Open"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"}}}},"/v1/analytics/jobs/{job_id}/export":{"get":{"tags":["analytics"],"summary":"Every underlying rate row of an analysis as CSV or Parquet (codes only, no descriptors)","operationId":"export_market_analysis","security":[{"HTTPBearer":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"format","in":"query","required":false,"schema":{"enum":["csv","parquet"],"type":"string","default":"csv","title":"Format"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}},"text/csv":{},"application/vnd.apache.parquet":{}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"}}}},"/v1/guide":{"get":{"tags":["guide"],"summary":"Guide topics","operationId":"guide_index","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/guide/{topic}":{"get":{"tags":["guide"],"summary":"One guide topic (markdown)","operationId":"guide_topic","parameters":[{"name":"topic","in":"path","required":true,"schema":{"type":"string","title":"Topic"}}],"responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"content":{"text/plain":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not Found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/workflows":{"get":{"tags":["guide"],"summary":"Arazzo 1.0 workflows (JSON)","operationId":"list_workflows","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/workflows/{workflow_id}":{"get":{"tags":["guide"],"summary":"One workflow as agent-readable markdown","operationId":"get_workflow","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}}],"responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"content":{"text/plain":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not Found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/me":{"get":{"tags":["admin"],"summary":"The caller's key/token and scopes","operationId":"whoami","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/admin/keys":{"get":{"tags":["admin"],"summary":"List API keys (no secrets)","operationId":"list_api_keys","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyList"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["admin"],"summary":"Mint an API key","description":"Returns the secret once; only its sha256 hash is stored.","operationId":"create_api_key","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreated"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/admin/keys/{key_id}":{"delete":{"tags":["admin"],"summary":"Revoke an API key","operationId":"revoke_api_key","security":[{"HTTPBearer":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"204":{"description":"Successful Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment Required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too Many Requests"}}}}},"components":{"schemas":{"Affiliation":{"properties":{"status":{"type":"string","enum":["is_hospital","likely_hospital_owned","possible_hospital_affiliation","none_found"],"title":"Status"},"evidence":{"items":{"type":"string"},"type":"array","title":"Evidence","default":[]},"meaning":{"type":"string","title":"Meaning","default":""}},"additionalProperties":true,"type":"object","required":["status"],"title":"Affiliation"},"AnalyticsRequest":{"properties":{"codes":{"items":{"type":"string"},"type":"array","maxItems":20,"minItems":1,"title":"Codes","description":"1-20 CPT/HCPCS codes from find_codes. Codes that hospitals are paid per APC also bring in the hospitals' APC case rates."},"geography":{"$ref":"#/components/schemas/Geography"},"payers":{"items":{"type":"string"},"type":"array","title":"Payers","description":"Insurer names as people say them (\"Premera\", \"Aetna\", \"Regence\", \"UnitedHealthcare\", \"Cigna\", \"Kaiser\"), catalog payer ids, or [\"major\"] = the largest insurers in this market (major_payers of them)."},"major_payers":{"type":"integer","maximum":8.0,"minimum":1.0,"title":"Major Payers","description":"How many insurers \"major\" means.","default":5},"files_per_payer":{"type":"integer","maximum":40.0,"minimum":1.0,"title":"Files Per Payer","description":"Most rate files read per insurer (in-area and most-used files first). More = more coverage, more first-time indexing (time, price).","default":8},"index_new_files":{"type":"boolean","title":"Index New Files","description":"false = read only files that are already indexed (fast, nearly free; coverage may be lower). true = also index the in-scope files that are not yet indexed.","default":true},"providers":{"type":"string","enum":["relevant","all"],"title":"Providers","description":"relevant = billing entities with evidence they provide the service (Medicare billing for the code, facility, hospital APC); all = also entities that merely hold a contracted rate.","default":"relevant"},"include_providers":{"type":"boolean","title":"Include Providers","description":"Add the least / most expensive billing entities (name, TIN, site address, miles) to each result group.","default":false},"providers_per_group":{"type":"integer","maximum":25.0,"minimum":1.0,"title":"Providers Per Group","default":5},"max_price_usd":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Max Price Usd","description":"Highest estimated usage charge (USD) the job may start with (default $1.00); above it the job is not started (409 price_confirmation_required)."}},"type":"object","required":["codes","geography"],"title":"AnalyticsRequest"},"ApiKey":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"created":{"type":"number","title":"Created"},"revoked":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revoked"}},"additionalProperties":true,"type":"object","required":["id","name","scopes","created"],"title":"ApiKey"},"ApiKeyCreated":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"key":{"type":"string","title":"Key","description":"The secret. Shown once; only a hash is stored."}},"additionalProperties":true,"type":"object","required":["id","name","scopes","key"],"title":"ApiKeyCreated"},"ApiKeyList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ApiKey"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Cursor"}},"additionalProperties":true,"type":"object","required":["data"],"title":"ApiKeyList"},"Area":{"properties":{"zip":{"type":"string","title":"Zip","description":"5-digit ZIP the person is near.","examples":["98052"]},"miles":{"type":"number","maximum":100.0,"minimum":1.0,"title":"Miles","description":"Search radius in miles.","default":15}},"type":"object","required":["zip"],"title":"Area"},"Billing":{"properties":{"billing_class":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Billing Class","description":"professional (clinician claim) | institutional (facility claim)"},"setting":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Setting"},"modifiers":{"items":{"type":"string"},"type":"array","title":"Modifiers","default":[]},"component":{"type":"string","title":"Component","description":"global | professional_component | technical_component | professional | facility | drug"},"applies_when":{"type":"string","title":"Applies When"},"place_of_service":{"type":"string","title":"Place Of Service","description":"non_facility | facility | mixed | unspecified"}},"additionalProperties":true,"type":"object","required":["component","applies_when","place_of_service"],"title":"Billing"},"BillingEntity":{"properties":{"tin":{"type":"string","title":"Tin"},"name":{"type":"string","title":"Name"},"is_hospital":{"type":"boolean","title":"Is Hospital"},"clinicians_on_roster":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Clinicians On Roster"},"matches_location_npis":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Matches Location Npis"},"hospital_affiliation":{"anyOf":[{"$ref":"#/components/schemas/Affiliation"},{"type":"null"}]},"health_system":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Health System","description":"{name, ccn, ownership, source}: source = why (the entity is the hospital / shares clinicians with a hospital TIN / name match only)."},"ccn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ccn","description":"CMS Certification Number when the entity is an identified hospital."},"sites":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Sites","description":"Places to go near the ZIP: organization NPI / practice address / hospital campus with address, taxonomy, miles to the site, fit for the service.","default":[]}},"additionalProperties":true,"type":"object","required":["tin","name","is_hospital"],"title":"BillingEntity"},"ClaimLine":{"properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code","description":"CPT/HCPCS code on the bill (from the bill/EOB or find_codes). Leave empty when a hospital bill shows only a revenue category, and give revenue_category instead."},"revenue_category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Category","description":"For hospital bills without codes: the line as printed, e.g. \"Radiology - Diagnostic\", \"Laboratory\", \"Emergency Room\", \"CT scan\", \"Pharmacy\". Priced as each hospital outpatient payment group (APC) that category can be; reconciliation then shows which one matches the allowed amount."},"units":{"type":"number","exclusiveMinimum":0.0,"title":"Units","default":1},"modifiers":{"items":{"type":"string"},"type":"array","title":"Modifiers","description":"e.g. [\"26\"] or [\"TC\"]."},"billed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Billed","description":"Billed charge for the line (needed for percent-of-charges contracts)."},"allowed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Allowed","description":"Allowed amount for this line from the EOB, if shown."}},"type":"object","title":"ClaimLine"},"ClaimLineResult":{"properties":{"code":{"type":"string","title":"Code"},"units":{"type":"number","title":"Units"},"status_indicator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Indicator"},"options":{"items":{"$ref":"#/components/schemas/ClaimOption"},"type":"array","title":"Options","description":"The rule-based rate each candidate billing entity would be paid."},"expected_range":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"null"}],"title":"Expected Range"},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","default":[]}},"additionalProperties":true,"type":"object","required":["code","units","options"],"title":"ClaimLineResult"},"ClaimOption":{"properties":{"tin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tin"},"entity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity"},"amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount"},"method":{"type":"string","title":"Method"},"confidence":{"type":"string","title":"Confidence"}},"additionalProperties":true,"type":"object","required":["method","confidence"],"title":"ClaimOption"},"ClaimRequest":{"properties":{"coverage":{"$ref":"#/components/schemas/Coverage","description":"type plan (with plan_id) or medicare. type hospital is rejected (400 claim_coverage_unsupported): hospital price-file rates are per code; use get_rates."},"zip":{"type":"string","title":"Zip","examples":["98052"]},"lines":{"items":{"$ref":"#/components/schemas/ClaimLine"},"type":"array","maxItems":40,"minItems":1,"title":"Lines"},"billing_entities":{"items":{"$ref":"#/components/schemas/Entity"},"type":"array","title":"Billing Entities","description":"Candidate billing entities (TINs); each line is priced at each. Include the owning hospital's TIN for hospital-owned clinics."},"place_of_service":{"type":"string","enum":["office","hospital_outpatient","facility","unknown"],"title":"Place Of Service","description":"office = clinic / urgent care / doctor's office (\"physician services\"); hospital_outpatient = hospital outpatient department, hospital imaging or lab (\"hospital services\").","default":"unknown"},"claim_allowed_total":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Claim Allowed Total","description":"Actual allowed amount from the bill/EOB, to reconcile."},"miles":{"type":"number","maximum":100.0,"minimum":1.0,"title":"Miles","default":15},"wait_seconds":{"type":"integer","maximum":240.0,"minimum":5.0,"title":"Wait Seconds","default":90}},"type":"object","required":["coverage","zip","lines"],"title":"ClaimRequest"},"ClaimResult":{"properties":{"lines":{"items":{"$ref":"#/components/schemas/ClaimLineResult"},"type":"array","title":"Lines"},"billing_entities":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Billing Entities"},"per_entity_totals":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Per Entity Totals"},"expected_total_range":{"items":{"type":"number"},"type":"array","title":"Expected Total Range"},"reconciliation":{"anyOf":[{"$ref":"#/components/schemas/Reconciliation"},{"type":"null"}]},"needs":{"items":{"$ref":"#/components/schemas/Need"},"type":"array","title":"Needs","default":[]},"next_steps":{"items":{"type":"string"},"type":"array","title":"Next Steps","default":[]}},"additionalProperties":true,"type":"object","required":["lines","billing_entities","per_entity_totals","expected_total_range"],"title":"ClaimResult"},"Code":{"properties":{"code_type":{"type":"string","title":"Code Type"},"code":{"type":"string","title":"Code"},"plain_name":{"type":"string","title":"Plain Name"},"official_description":{"type":"string","title":"Official Description","default":""},"category":{"type":"string","title":"Category","default":""},"facts":{"$ref":"#/components/schemas/CodeFacts"}},"additionalProperties":true,"type":"object","required":["code_type","code","plain_name","facts"],"title":"Code"},"CodeFacts":{"properties":{"hospital_outpatient":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Hospital Outpatient","description":"OPPS status indicator, APC, packaging rule."},"medicare_physician_fee":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Medicare Physician Fee"},"medicare_clinical_lab_fee":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Medicare Clinical Lab Fee","description":"Lab tests: Medicare lab fee (ESTIMATED; the CMS CLFS file is behind the AMA license)."},"medicare_drug_payment_limit":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Medicare Drug Payment Limit","description":"Part B drugs: ASP payment limit per billing unit."},"medicare_only_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Medicare Only Code"},"timed_units":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timed Units"},"add_on_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Add On Code"}},"additionalProperties":true,"type":"object","title":"CodeFacts"},"CodesResult":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Code"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Cursor"},"setting":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Setting","description":"Where care happens, when the words name it (urgent care, ER, telehealth, hospital outpatient, ASC, home, office): id, name, CMS place of service `pos` (+ `pos_options`), `note` on how that setting bills, `visit_codes`."},"clarify":{"items":{"type":"string"},"type":"array","title":"Clarify","default":[]},"needs":{"items":{"$ref":"#/components/schemas/Need"},"type":"array","title":"Needs","default":[]},"next_steps":{"items":{"type":"string"},"type":"array","title":"Next Steps","default":[]}},"additionalProperties":true,"type":"object","required":["data"],"title":"CodesResult"},"Coverage":{"properties":{"type":{"type":"string","enum":["plan","medicare","hospital"],"title":"Type","description":"plan = a plan from find_plan (insurer rate files); medicare = Original Medicare fee schedule; hospital = hospitals' own price files (Medicare Advantage, Medicaid, cash/self-pay): each hospital's posted rate per payer/plan as the hospital wrote it (not necessarily the person's plan), mostly facility charges; cash = its discounted cash price, not the gross charge. price_claim does not accept hospital.","default":"plan"},"plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Id","description":"Required when type = plan; from find_plan."},"hospital_coverage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hospital Coverage","description":"For type = hospital: medicare_advantage | medicaid | cash | a payer name."}},"type":"object","title":"Coverage"},"Entity":{"properties":{"tin":{"type":"string","title":"Tin","description":"Billing entity tax ID from find_providers (billing_entities or related_entities)."}},"type":"object","required":["tin"],"title":"Entity"},"Error":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"Error"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code","description":"Stable machine-readable error code, e.g. plan_not_found, invalid_zip, unauthorized."},"message":{"type":"string","title":"Message"},"hint":{"type":"string","title":"Hint","default":""}},"type":"object","required":["code","message"],"title":"ErrorBody"},"Geography":{"properties":{"zip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zip","description":"5-digit ZIP at the center of a radius, e.g. 98052.","examples":["98052"]},"miles":{"anyOf":[{"type":"number","maximum":100.0,"minimum":1.0},{"type":"null"}],"title":"Miles","description":"Radius around zip in miles (default 25)."},"metro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metro","description":"Metro area name as in CMS CBSA names, e.g. \"Seattle\", \"Tacoma\", \"Denver-Aurora\" (a CBSA / metropolitan division)."},"cbsa":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cbsa","description":"CBSA or metropolitan-division code, e.g. 42644 (Seattle-Bellevue-Kent, WA)."},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"2-letter state, e.g. WA (large: slower and costlier than a metro or a radius)."}},"type":"object","title":"Geography","description":"The market: one of zip (+ miles), metro, cbsa or state."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"KeyRequest":{"properties":{"name":{"type":"string","title":"Name","description":"Who/what the key is for."},"scopes":{"items":{"type":"string","enum":["read","admin"]},"type":"array","title":"Scopes","default":["read"]},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"Owning account for usage/billing (default: the key name)."}},"type":"object","required":["name"],"title":"KeyRequest"},"Location":{"properties":{"npi":{"type":"string","title":"Npi"},"kind":{"type":"string","enum":["organization","individual"],"title":"Kind"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"specialty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Specialty"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"miles":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Miles"},"medicare_billed_2024":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Medicare Billed 2024","description":"Medicare CY2024 services billed per code by this NPI."}},"additionalProperties":true,"type":"object","required":["npi","kind"],"title":"Location"},"Need":{"properties":{"field":{"type":"string","title":"Field","description":"The missing input or condition, e.g. which_insurer, place_of_service, wait."},"why":{"type":"string","title":"Why","description":"Why it changes the answer and what to do."}},"additionalProperties":true,"type":"object","required":["field","why"],"title":"Need"},"Open":{"properties":{},"additionalProperties":true,"type":"object","title":"Open"},"Plan":{"properties":{"plan_id":{"type":"string","title":"Plan Id","description":"Pass as coverage.plan_id."},"payer":{"type":"string","title":"Payer"},"plan_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Name"},"sponsor_employer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sponsor Employer"},"sponsor_location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sponsor Location"},"plan_id_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Id Type","description":"ein (employer plan) or hios (marketplace) ..."},"plan_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Identifier"},"market":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market"},"rate_files":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rate Files"},"price_source":{"type":"string","title":"Price Source"}},"additionalProperties":true,"type":"object","required":["plan_id","payer","price_source"],"title":"Plan"},"PlanDetail":{"properties":{"plan":{"additionalProperties":true,"type":"object","title":"Plan"},"rate_files":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Rate Files"}},"additionalProperties":true,"type":"object","required":["plan","rate_files"],"title":"PlanDetail"},"PlanList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Plan"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Cursor"},"needs":{"items":{"$ref":"#/components/schemas/Need"},"type":"array","title":"Needs","default":[]},"next_steps":{"items":{"type":"string"},"type":"array","title":"Next Steps","default":[]}},"additionalProperties":true,"type":"object","required":["data"],"title":"PlanList"},"Price":{"properties":{"kind":{"type":"string","title":"Kind","description":"negotiated | fee_schedule | derived | per_diem | percent_of_charges | placeholder | algorithm ..."},"amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount","description":"Allowed dollars per unit; null when not a dollar price."},"percent":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Percent"},"unit":{"type":"string","title":"Unit","description":"per_service | per_day | per_apc_case | percent_of_billed_charges | none"},"is_dollar_price":{"type":"boolean","title":"Is Dollar Price"}},"additionalProperties":true,"type":"object","required":["kind","unit","is_dollar_price"],"title":"Price"},"Providers":{"properties":{"tins":{"items":{"type":"string"},"type":"array","title":"Tins","description":"Billing entity tax IDs (from find_providers), e.g. 84-1179794."},"npis":{"items":{"type":"string"},"type":"array","title":"Npis","description":"NPIs of locations or clinicians."},"names":{"items":{"type":"string"},"type":"array","title":"Names","description":"Substring match on billing entity / location names."}},"type":"object","title":"Providers"},"ProvidersResult":{"properties":{"locations":{"items":{"$ref":"#/components/schemas/Location"},"type":"array","title":"Locations"},"next_cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Cursor"},"billing_entities":{"items":{"$ref":"#/components/schemas/BillingEntity"},"type":"array","title":"Billing Entities","default":[]},"related_entities":{"items":{"$ref":"#/components/schemas/RelatedEntity"},"type":"array","title":"Related Entities","default":[]},"sites":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Sites","description":"Best sites across billing entities: a city named in the query first, then entity rank, service fit and distance to the site.","default":[]},"other_name_matches":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Other Name Matches","description":"Same-word names of a different specialty (dental, eye, …) set aside.","default":[]},"needs":{"items":{"$ref":"#/components/schemas/Need"},"type":"array","title":"Needs","default":[]},"next_steps":{"items":{"type":"string"},"type":"array","title":"Next Steps","default":[]}},"additionalProperties":true,"type":"object","required":["locations"],"title":"ProvidersResult"},"RateRow":{"properties":{"code":{"type":"string","title":"Code"},"code_type":{"type":"string","title":"Code Type"},"billing_entity":{"additionalProperties":true,"type":"object","title":"Billing Entity","description":"{tin, name, is_hospital}: prices belong to billing entities."},"location":{"additionalProperties":true,"type":"object","title":"Location"},"price":{"$ref":"#/components/schemas/Price"},"billing":{"$ref":"#/components/schemas/Billing"},"hospital_outpatient":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Hospital Outpatient","description":"APC, status indicator, packaging (institutional rows)."},"benchmark":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Benchmark","description":"Medicare amount for the same service/setting + percent_of_medicare."},"flags":{"items":{"type":"string"},"type":"array","title":"Flags","default":[]},"quality":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Quality","description":"{score 1-5, reason}: 5 corroborated by the hospital's own file, 4 consistent with Medicare band, 3 unchecked / not corroborated, 2 unusual, 1 not a usable dollar price (guide://fields)."},"hospital_file_rate":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Hospital File Rate","description":"Hospital rows: the same hospital's own price file for this payer and code (amount, plan_as_written, agreement, difference_percent)."},"evidence":{"additionalProperties":true,"type":"object","title":"Evidence"},"provenance":{"additionalProperties":true,"type":"object","title":"Provenance","description":"payer, plan, files, insurer_date_label vs retrieved_at, future_dated_label."}},"additionalProperties":true,"type":"object","required":["code","code_type","billing_entity","location","price","billing","evidence","provenance"],"title":"RateRow"},"RatesBatchItem":{"properties":{"index":{"type":"integer","title":"Index"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"ok":{"type":"boolean","title":"Ok"},"data":{"anyOf":[{"items":{"$ref":"#/components/schemas/RateRow"},"type":"array"},{"type":"null"}],"title":"Data"},"error":{"anyOf":[{"$ref":"#/components/schemas/ErrorBody"},{"type":"null"}]}},"additionalProperties":true,"type":"object","required":["index","ok"],"title":"RatesBatchItem"},"RatesBatchRequest":{"properties":{"requests":{"items":{"$ref":"#/components/schemas/RatesRequest"},"type":"array","maxItems":10,"minItems":1,"title":"Requests"}},"type":"object","required":["requests"],"title":"RatesBatchRequest"},"RatesBatchResult":{"properties":{"data":{"items":{"$ref":"#/components/schemas/RatesBatchItem"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Cursor"},"next_steps":{"items":{"type":"string"},"type":"array","title":"Next Steps","default":[]}},"additionalProperties":true,"type":"object","required":["data"],"title":"RatesBatchResult"},"RatesRequest":{"properties":{"coverage":{"$ref":"#/components/schemas/Coverage"},"codes":{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1,"title":"Codes","description":"Billing codes from find_codes (CPT/HCPCS, or an APC number for hospital case rates)."},"providers":{"anyOf":[{"$ref":"#/components/schemas/Providers"},{"type":"null"}],"description":"Restrict to these billing entities / locations."},"area":{"$ref":"#/components/schemas/Area"},"limit":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Limit","default":50},"cursor":{"type":"integer","minimum":0.0,"title":"Cursor","description":"Pagination cursor from next_cursor.","default":0},"wait_seconds":{"type":"integer","maximum":240.0,"minimum":5.0,"title":"Wait Seconds","description":"How long to wait for rate files being indexed for the first time.","default":60},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"Echoed back in batch results."}},"type":"object","required":["coverage","codes","area"],"title":"RatesRequest"},"RatesResult":{"properties":{"data":{"items":{"$ref":"#/components/schemas/RateRow"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Cursor"},"total_rows":{"type":"integer","title":"Total Rows"},"summary":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Summary","default":[]},"cheapest_sites":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Cheapest Sites","description":"Per code x component: the cheapest real places to go (site, address, miles to the site, TIN, amount, quality).","default":[]},"hospital_file_check":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Hospital File Check","description":"How many hospital rows were compared with the hospitals' own price files, and how many agree."},"medicare_reference":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Medicare Reference","description":"coverage medicare: per code OPPS wage-adjusted APC, estimated lab fee, ASP drug limit."},"coverage":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Coverage"},"needs":{"items":{"$ref":"#/components/schemas/Need"},"type":"array","title":"Needs","default":[]},"next_steps":{"items":{"type":"string"},"type":"array","title":"Next Steps","default":[]}},"additionalProperties":true,"type":"object","required":["data","total_rows"],"title":"RatesResult"},"Reconciliation":{"properties":{"actual_allowed_total":{"type":"number","title":"Actual Allowed Total"},"best_match_total":{"type":"number","title":"Best Match Total"},"difference":{"type":"number","title":"Difference"},"difference_percent":{"type":"number","title":"Difference Percent"},"verdict":{"type":"string","enum":["explained","plausible","unexplained"],"title":"Verdict"},"best_match":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Best Match"},"explanation":{"type":"string","title":"Explanation"},"interpretation":{"type":"string","title":"Interpretation"},"caveat":{"type":"string","title":"Caveat"}},"additionalProperties":true,"type":"object","required":["actual_allowed_total","best_match_total","difference","difference_percent","verdict","best_match","explanation","interpretation","caveat"],"title":"Reconciliation"},"RelatedEntity":{"properties":{"tin":{"type":"string","title":"Tin"},"name":{"type":"string","title":"Name"},"is_hospital":{"type":"boolean","title":"Is Hospital"},"shared_clinicians":{"type":"integer","title":"Shared Clinicians"},"why":{"type":"string","title":"Why"},"hospital_affiliation":{"anyOf":[{"$ref":"#/components/schemas/Affiliation"},{"type":"null"}]}},"additionalProperties":true,"type":"object","required":["tin","name","is_hospital","shared_clinicians","why"],"title":"RelatedEntity"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","description":"API key (tic_live_...) or OAuth access token.","scheme":"bearer"},"oauth2":{"type":"oauth2","description":"OAuth 2.1 (authorization code + PKCE) for MCP clients; see /.well-known/oauth-authorization-server","flows":{"authorizationCode":{"authorizationUrl":"/authorize","tokenUrl":"/token","scopes":{"read":"Query prices"}}}}}},"tags":[{"name":"plans","description":"Which plan (and rate files) applies to a person."},{"name":"providers","description":"Places and clinicians → billing entities (TINs)."},{"name":"codes","description":"Services in words → billing codes + code facts."},{"name":"rates","description":"Self-describing negotiated rate rows."},{"name":"claims","description":"Price or reconcile a whole visit / bill."},{"name":"analytics","description":"Market analytics: rate distributions per insurer across all providers in an area (scoped, just-in-time, async jobs)."},{"name":"guide","description":"Domain guide and Arazzo workflows (no auth)."},{"name":"admin","description":"API key management (admin scope)."}],"x-workflow-renderer":"builtin"}