{"openapi":"3.1.0","info":{"title":"ICD-10 Coding API","description":"\n    Professional ICD-10-CM coding API with database-verified accuracy.\n\n    ## Features\n\n    - **Code Lookup**: Full tabular details with inherited notes\n    - **Index Search**: Alphabetic index navigation\n    - **Abbreviation Expansion**: DM2 → diabetes mellitus type 2\n    - **AI Coding**: Natural language → ICD-10 codes (Pro tier)\n    - **HCC Information**: Risk adjustment mappings\n    - **Batch Operations**: Bulk lookups (Pro tier)\n\n    ## Authentication\n\n    All endpoints require an API key via `Authorization: Bearer <key>` or `X-API-Key` header.\n\n    ## Rate Limits\n\n    | Tier | Requests/Day | Requests/Min |\n    |------|-------------|--------------|\n    | Free | 100 | 10 |\n    | Pro | 10,000 | 100 |\n    | Enterprise | Unlimited | 500 |\n\n    ## MCP Server\n\n    This API also provides an MCP server for integration with Claude, Cursor,\n    and Windsurf. See `/mcp` endpoints for details.\n    ","version":"0.2.1"},"paths":{"/health":{"get":{"tags":["health"],"summary":"Health Check","description":"Basic health check.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Check Health Get"}}}}}}},"/health/ready":{"get":{"tags":["health"],"summary":"Readiness Check","description":"Readiness check including database and Redis connectivity.\n\nReturns 503 if database is not reachable. Internal details are logged,\nnot exposed.","operationId":"readiness_check_health_ready_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health/coding":{"get":{"tags":["health"],"summary":"Coding Readiness Check","description":"Can this revision actually CODE, or only pass a health check?\n\nSEPARATE FROM /health/ready ON PURPOSE, and it is the whole point of the endpoint.\n`/health/ready` is what the platform routes on: a 503 there pulls the replica out of\nrotation, which is why Redis is fail-open there. Reference data being unbuilt is the\nopposite shape — it must STOP A DEPLOY, and must never pull a serving replica. Folding\nthis into readiness would trade a silent accuracy loss for a self-inflicted outage.\n\nSo: always 200, nothing routes on it, and the deploy smoke test is the only consumer.\nIt fails the canary before traffic shifts; a live replica is never affected.\n\nBody is `{\"status\": ...}` and nothing else TO AN ANONYMOUS CALLER, matching /health/ready's\nstance — naming which subsystem is dark on an unauthenticated endpoint is the SOC2\ninfo-disclosure control. The detail is logged.\n\n⚠ A VALID `X-API-Key` ADDS A `channels` MAP (2026-08-30, DATA-H2/H3), and nothing else\nchanges. One status word tells an operator that the canary refused and not which of ten\nchannels refused it, which leaves them reading Container App console logs during a blocked\ndeploy. The breakdown is therefore returned — but only to an authenticated caller, exactly\nthe stance /health/migrations and /health/data-integrity already take for endpoints that\nname internal table state. The anonymous body is byte-identical to before, so the deploy\nsmoke test (templates/steps-smoke-test.yml), which calls this without a key and greps\n`\"status\"` out of the body with a GREEDY regex, is unaffected. Keep it that way: the\nchannel map is deliberately `{name: word}` with no nested `\"status\"` key, because a second\n`\"status\"` anywhere in this body would make that regex read the LAST one and silently\ninvert the gate.\n\n⚠ A VALID KEY ALSO ADDS A `client` BLOCK (2026-08-30, SEC-M6 live check ③) —\n`{peer, forwarded, xff_depth}`, the three values that make `TRUSTED_PROXY_HOPS`\nverifiable with a single curl. See `_forwarded_diagnostics`. Same authenticated-only\nstance and the same no-nested-`\"status\"` rule as `channels`.\n\n``?year=`` probes a specific fiscal year. Without it this only ever answered for\n``DEFAULT_ICD10_YEAR``, while a request may carry any ``body.year`` (see\napi/v1/code.py) — so a client coding FY2025 against a deployment whose reference data\nexists only for FY2026 got a green health check and a silently degraded coding path.\nThat is the serving-time shape of KB trap T1. The parameter is additive: the no-argument\ncall the deploy smoke test makes behaves exactly as before.\n\nTWO CHECKS, ONE STATUS WORD (cross-year integrity added 2026-08-11).\nReference data fails in two shapes and only one of them is about a year being ABSENT:\n\n  * ``check_coding_readiness`` — is the data this year needs THERE (corpus built,\n    vocabulary loaded)? Absent data.\n  * ``check_cross_year``       — was each year actually LOADED, or copied from the year\n    before it? Present data that is silently WRONG, which no readiness probe can see\n    because every table it looks at is populated.\n\nThe second used to be Gate C: a snapshot file produced by hand on the jump VM, committed\nto the repo, and read by the CI stage. That design had three defects — nothing refreshed\nit (so it expired and froze every merge), it gated PRs on a deploy-time concern, and it\ndescribed the database at some past moment rather than the one this revision will serve.\nIt is now computed here, live, on the canary before traffic shifts. ~0.85s for 13 datasets\nacross a three-year window; this endpoint has exactly one consumer, so that is affordable.\n\n⚠ ERRORS block, WARNINGS do not. An identical codeset across two years is often correct —\nthe IPPS sex edit was deactivated 2024-10-01, so an unchanged set there is the EXPECTED\nstate. `check_cross_year` already encodes that distinction; re-deciding it here would\nduplicate the judgement in the place least able to make it.","operationId":"coding_readiness_check_health_coding_get","parameters":[{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/":{"get":{"tags":["info"],"summary":"Root","description":"API information.","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Root  Get"}}}}}}},"/api/v1/codes/{code}":{"get":{"tags":["codes"],"summary":"Get Code","description":"Look up an ICD-10-CM code with full tabular details.\n\nReturns the code description, chapter/section info, and all instructional\nnotes (includes, excludes, code first, use additional code, etc.).\n\nWhen include_inherited=true (default), notes from parent categories are\nalso included, providing complete coding guidance.\n\nWhen include_hcc=true, HCC risk adjustment mappings are included inline\nin the response as `hcc_mappings`. Add include_weights=true to attach\nRAF weights to each HCC category.","operationId":"get_code_api_v1_codes__code__get","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"ICD-10-CM code (e.g., E11.22)","title":"Code"},"description":"ICD-10-CM code (e.g., E11.22)"},{"name":"year","in":"query","required":false,"schema":{"type":"integer","description":"Fiscal year version","title":"Year"},"description":"Fiscal year version"},{"name":"include_inherited","in":"query","required":false,"schema":{"type":"boolean","description":"Include inherited notes from parent categories","default":true,"title":"Include Inherited"},"description":"Include inherited notes from parent categories"},{"name":"include_hcc","in":"query","required":false,"schema":{"type":"boolean","description":"Include inline HCC risk adjustment mappings","default":false,"title":"Include Hcc"},"description":"Include inline HCC risk adjustment mappings"},{"name":"include_weights","in":"query","required":false,"schema":{"type":"boolean","description":"Include HCC RAF weights (requires include_hcc)","default":false,"title":"Include Weights"},"description":"Include HCC RAF weights (requires include_hcc)"},{"name":"payment_year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Payment year for weight lookup","title":"Payment Year"},"description":"Payment year for weight lookup"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Code Api V1 Codes  Code  Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/codes/{code}/hcc":{"get":{"tags":["codes"],"summary":"Get Code Hcc","description":"Get HCC (Hierarchical Condition Category) information for a code.\n\nReturns risk adjustment mappings for:\n- CMS-HCC (Medicare Advantage)\n- RxHCC (Part D)\n- HHS-HCC (ACA marketplace)\n- ESRD\n\nWhen detail=true, includes per-symbol breakdown with model type,\nversion code, category, and payment flags.\n\nWhen include_weights=true, attaches RAF weights to each category.","operationId":"get_code_hcc_api_v1_codes__code__hcc_get","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"ICD-10-CM code","title":"Code"},"description":"ICD-10-CM code"},{"name":"year","in":"query","required":false,"schema":{"type":"integer","description":"Fiscal year version","title":"Year"},"description":"Fiscal year version"},{"name":"detail","in":"query","required":false,"schema":{"type":"boolean","description":"Include detailed symbol breakdown and payment flags","default":false,"title":"Detail"},"description":"Include detailed symbol breakdown and payment flags"},{"name":"include_weights","in":"query","required":false,"schema":{"type":"boolean","description":"Include RAF weights for each category","default":false,"title":"Include Weights"},"description":"Include RAF weights for each category"},{"name":"payment_year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Payment year for weight lookup","title":"Payment Year"},"description":"Payment year for weight lookup"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Code Hcc Api V1 Codes  Code  Hcc Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/codes/{code}/children":{"get":{"tags":["codes"],"summary":"Get Children","description":"Get all child codes under a parent category.\n\nUseful for exploring subcategories, e.g., E11 returns E11.0, E11.1, etc.","operationId":"get_children_api_v1_codes__code__children_get","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"Parent ICD-10-CM code (e.g., E11 for all E11.x codes)","title":"Code"},"description":"Parent ICD-10-CM code (e.g., E11 for all E11.x codes)"},{"name":"year","in":"query","required":false,"schema":{"type":"integer","description":"Fiscal year version","title":"Year"},"description":"Fiscal year version"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Children Api V1 Codes  Code  Children Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/search":{"get":{"tags":["search"],"summary":"Search","description":"Search for ICD-10-CM codes.\n\nTwo search modes:\n- **index** (default): Search the alphabetic index by medical terms.\n  Use main_term + subterms for hierarchical navigation (recommended),\n  or just q for free-text search.\n- **tabular**: Search code descriptions in the tabular list.\n  Useful when the alphabetic index doesn't have a direct match.\n\nExample hierarchical search:\n```\n?main_term=Diabetes&subterms=type+2&subterms=with&subterms=neuropathy&year=2025\n```","operationId":"search_api_v1_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":500,"description":"Search query","title":"Q"},"description":"Search query"},{"name":"year","in":"query","required":false,"schema":{"type":"integer","maximum":2030,"minimum":2014,"description":"Fiscal year version","title":"Year"},"description":"Fiscal year version"},{"name":"main_term","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Main index term for hierarchical search","title":"Main Term"},"description":"Main index term for hierarchical search"},{"name":"subterms","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":10},{"type":"null"}],"description":"Subterms for hierarchical refinement","title":"Subterms"},"description":"Subterms for hierarchical refinement"},{"name":"mode","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SearchMode","description":"Search mode: 'index' (alphabetic) or 'tabular' (descriptions)","default":"index"},"description":"Search mode: 'index' (alphabetic) or 'tabular' (descriptions)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum results","default":20,"title":"Limit"},"description":"Maximum results"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Search Api V1 Search Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/search/suggest":{"get":{"tags":["search"],"summary":"Suggest","description":"Get search suggestions for autocomplete.\n\nReturns quick suggestions based on partial input, optimized for\ntypeahead/autocomplete UI components.","operationId":"suggest_api_v1_search_suggest_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":500,"description":"Partial search query","title":"Q"},"description":"Partial search query"},{"name":"year","in":"query","required":false,"schema":{"type":"integer","maximum":2030,"minimum":2014,"description":"Fiscal year version","title":"Year"},"description":"Fiscal year version"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum suggestions","default":10,"title":"Limit"},"description":"Maximum suggestions"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Suggest Api V1 Search Suggest Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/expand":{"post":{"tags":["expand"],"summary":"Expand Text","description":"Expand medical abbreviations in text.\n\nRecognizes common medical abbreviations like:\n- DM2 → diabetes mellitus type 2\n- w/ → with\n- CKD → chronic kidney disease\n- HTN → hypertension\n- CHF → congestive heart failure\n- COPD → chronic obstructive pulmonary disease\n\nAlso provides hints for alphabetic index navigation (main_term_hint,\nsubterm_hints) which are useful for subsequent code lookups.\n\n**Example:**\n```json\n{\"text\": \"DM2 w/ CKD stage 3\"}\n```\n\n**Response:**\n```json\n{\n  \"expanded_text\": \"diabetes mellitus type 2 with chronic kidney disease stage 3\",\n  \"expansions\": [\n    {\"original\": \"DM2\", \"expanded\": \"diabetes mellitus type 2\", ...},\n    {\"original\": \"w/\", \"expanded\": \"with\", ...},\n    {\"original\": \"CKD\", \"expanded\": \"chronic kidney disease\", ...}\n  ]\n}\n```\n\nFree-tier keys are limited to 500 characters of input; Pro and Enterprise keys may\nsend the full 10,000. Over the limit returns 413. This endpoint normalizes shorthand\nbefore an index lookup — it is not intended for whole clinical notes.","operationId":"expand_text_api_v1_expand_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpandRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Expand Text Api V1 Expand Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/expand/term":{"post":{"tags":["expand"],"summary":"Expand Single Term","description":"Expand a single medical abbreviation.\n\nReturns the standard term along with navigation hints for the\nalphabetic index (main_term_hint, subterm_hints).\n\nSupports fuzzy matching for typos and variations.","operationId":"expand_single_term_api_v1_expand_term_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpandTermRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Expand Single Term Api V1 Expand Term Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/code":{"post":{"tags":["code"],"summary":"Code Condition","description":"Convert natural language condition to ICD-10-CM codes.\n\nUses an AI agent with function calling to implement the proper ICD-10\ncoding workflow:\n\n1. **Normalize input**: Expand abbreviations (DM2 → diabetes mellitus type 2)\n2. **Alphabetic index lookup**: Find candidate codes\n3. **Tabular verification**: Verify codes and check instructional notes\n4. **Combination code check**: Look for single codes covering multiple conditions\n5. **Structured response**: Return codes with reasoning and confidence\n\n**Example request:**\n```json\n{\n  \"condition\": \"DM2 w/ CKD stage 3\",\n  \"include_hcc\": true\n}\n```\n\n**Example response:**\n```json\n{\n  \"success\": true,\n  \"codes_mentioned\": [\"E11.22\", \"N18.3\"],\n  \"reasoning\": \"Type 2 diabetes with chronic kidney disease...\",\n  \"confidence\": \"high\",\n  \"warnings\": [],\n  \"tool_calls_made\": [...],\n  \"tokens_used\": 1234\n}\n```\n\n**Note:** This endpoint requires Pro or Enterprise tier.","operationId":"code_condition_api_v1_code_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeRequest"}}}},"responses":{"200":{"description":"Coding result. `data` is OPEN — keys are added over time and a client must ignore ones it does not know rather than reject the response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"CodeResponse","properties":{"success":{"type":"boolean"},"data":{"type":"object","description":"Engine output. Not exhaustive — see docs/API.md and docs/API_CHANGELOG.md for additions.","properties":{"codes_mentioned":{"type":"array","items":{"type":"string"},"description":"Final ICD-10-CM codes, in sequence order."},"code_evidence":{"type":"object","description":"code -> [chart span]. A list because the compiler can merge two documented concepts into one code, so a caller cannot rebuild it by joining on `code`."},"reasoning":{"type":"string"},"confidence":{"type":"string","examples":["high","medium","low"]},"warnings":{"type":"array","items":{"type":"string"}},"verification":{"type":"object","description":"Post-LLM verification report."},"documentation_gaps":{"type":"array","items":{}},"corpus_ready":{"type":"boolean","description":"Standing health of the retrieval corpus FOR THIS REQUEST'S fiscal year. False means the hybrid search channel was dark and recall was reduced."},"degradations":{"type":"array","description":"Everything that went wrong on THIS request, typed so a caller branches on `kind` instead of parsing prose. Empty = a clean run. ⚠ `kind` is an OPEN set (`search_corpus_dark`, `disambiguation_degraded`, `llm_circuit_open`, `terminology_unavailable` today) — ignore unknown kinds; do not assume the list is exhaustive.","items":{"type":"object","properties":{"kind":{"type":"string"}}}},"pipeline":{"type":"string","examples":["v2"]},"tokens_used":{"type":"integer"}}}},"required":["success","data"]}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/api/v1/code/review-queue":{"get":{"tags":["code"],"summary":"Review Queue","description":"Charts that fell below the autonomous_threshold and need human review.\n\nLists recent autonomous decisions where outcome=='human_review',\nscoped to the calling key's organization. Pro+ tier; only useful\nif autonomous mode has been configured.","operationId":"review_queue_api_v1_code_review_queue_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Review Queue Api V1 Code Review Queue Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/api/v1/code/autonomous-config":{"post":{"tags":["code"],"summary":"Update Autonomous Config","description":"Set the calling org's autonomous threshold + blocking severity.\n\nSetting `autonomous_threshold=null` disables autonomous mode (default\nbehavior; coded charts return without `auto_billable` field).","operationId":"update_autonomous_config_api_v1_code_autonomous_config_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutonomousConfigRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Update Autonomous Config Api V1 Code Autonomous Config Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/api/v1/code/stream":{"post":{"tags":["code"],"summary":"Code Condition Stream","description":"Stream AI coding agent events as Server-Sent Events.\n\nReturns the same result as POST /api/v1/code, but streams intermediate\nsteps (tool calls, tool results, verification) in real-time.\n\n**Event types:**\n- `agent_start` — coding session initiated\n- `tool_call` — agent is calling a tool\n- `tool_result` — tool returned a result\n- `verification` — post-LLM verification complete\n- `meat_extraction` — per-code MEAT evidence ready (only if a MEAT\n  profile is configured for the org)\n- `final_result` — full coding result (same shape as /code response)\n- `error` — something went wrong\n\n**Note:** Requires Pro or Enterprise tier.","operationId":"code_condition_stream_api_v1_code_stream_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/api/v1/ra/code":{"post":{"tags":["ra"],"summary":"Ra Code","description":"Run one encounter A1→D8 and return the ICD-10-CM codes. Flag-gated, opt-in.","operationId":"ra_code_api_v1_ra_code_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RaCodeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RaCodeResponse"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/code/sessions":{"post":{"tags":["sessions"],"summary":"Create Session","description":"Create a new multi-turn coding session.","operationId":"create_session_api_v1_code_sessions_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Session Api V1 Code Sessions Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/code/sessions/{session_id}/turn":{"post":{"tags":["sessions"],"summary":"Submit Turn","description":"Submit one turn against an existing coding session.","operationId":"submit_turn_api_v1_code_sessions__session_id__turn_post","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TurnRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Submit Turn Api V1 Code Sessions  Session Id  Turn Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/code/sessions/{session_id}":{"get":{"tags":["sessions"],"summary":"Get Session","description":"Read full session state (history + accumulated codes).","operationId":"get_session_api_v1_code_sessions__session_id__get","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Session Api V1 Code Sessions  Session Id  Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"delete":{"tags":["sessions"],"summary":"Close Session","description":"Mark a session closed. Idempotent — closing a closed session is a no-op.","operationId":"close_session_api_v1_code_sessions__session_id__delete","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/usage/me":{"get":{"tags":["usage"],"summary":"Get My Usage","description":"Return aggregate usage for the calling key in the given window (default last 30 days).","operationId":"get_my_usage_api_v1_usage_me_get","parameters":[{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO8601 lower bound (inclusive)","title":"Since"},"description":"ISO8601 lower bound (inclusive)"},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO8601 upper bound (exclusive)","title":"Until"},"description":"ISO8601 upper bound (exclusive)"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get My Usage Api V1 Usage Me Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/usage/aggregate":{"get":{"tags":["usage"],"summary":"Get Aggregate","description":"Aggregate the calling key's usage broken out by event_type + unit_kind.","operationId":"get_aggregate_api_v1_usage_aggregate_get","parameters":[{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Until"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Aggregate Api V1 Usage Aggregate Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/usage/events":{"get":{"tags":["usage"],"summary":"List Events","description":"Recent raw usage events for the calling key, newest first.","operationId":"list_events_api_v1_usage_events_get","parameters":[{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Until"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor (event id)","title":"Cursor"},"description":"Opaque cursor (event id)"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Events Api V1 Usage Events Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/roi/coverage":{"get":{"tags":["roi"],"summary":"Coverage","description":"% of AI coding requests that completed without errors.","operationId":"coverage_api_v1_roi_coverage_get","parameters":[{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Until"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Coverage Api V1 Roi Coverage Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/roi/specificity":{"get":{"tags":["roi"],"summary":"Specificity","description":"Count of codes assigned, broken into specific vs. unspecified.","operationId":"specificity_api_v1_roi_specificity_get","parameters":[{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Until"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Specificity Api V1 Roi Specificity Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/roi/hcc-capture":{"get":{"tags":["roi"],"summary":"Hcc Capture","description":"Count of HCC-eligible codes captured by AI coding.","operationId":"hcc_capture_api_v1_roi_hcc_capture_get","parameters":[{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Until"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Hcc Capture Api V1 Roi Hcc Capture Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/roi/throughput":{"get":{"tags":["roi"],"summary":"Throughput","description":"Daily coding + chart-review volume for the calling key.","operationId":"throughput_api_v1_roi_throughput_get","parameters":[{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Until"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Throughput Api V1 Roi Throughput Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/roi/summary":{"get":{"tags":["roi"],"summary":"Summary","description":"Single-call top-line ROI dashboard.","operationId":"summary_api_v1_roi_summary_get","parameters":[{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Until"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Summary Api V1 Roi Summary Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/batch/codes":{"post":{"tags":["batch"],"summary":"Batch Codes","description":"Look up multiple ICD-10-CM codes in a single request.\n\nReturns full code details for each code, including inherited notes\nwhen include_inherited=true.\n\n**Limits:**\n- Maximum 50 codes per request\n- Requires Pro or Enterprise tier\n\n**Example request:**\n```json\n{\n  \"codes\": [\"E11.22\", \"N18.3\", \"I10\"],\n  \"include_inherited\": true\n}\n```","operationId":"batch_codes_api_v1_batch_codes_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCodesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Batch Codes Api V1 Batch Codes Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/batch/hcc":{"post":{"tags":["batch"],"summary":"Batch Hcc","description":"Get HCC information for multiple codes in a single request.\n\nReturns a summary of HCC mappings for each code, indicating whether\nit maps to CMS-HCC, RxHCC, or HHS-HCC.\n\nWhen include_weights=true, RAF weights are included for each code's\nHCC categories.\n\n**Limits:**\n- Maximum 50 codes per request\n- Requires Pro or Enterprise tier\n\n**Example request:**\n```json\n{\n  \"codes\": [\"E11.22\", \"N18.3\", \"J06.9\"],\n  \"include_weights\": true\n}\n```","operationId":"batch_hcc_api_v1_batch_hcc_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchHCCRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Batch Hcc Api V1 Batch Hcc Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/batch/hcc/suppress":{"post":{"tags":["batch"],"summary":"Batch Hcc Suppress","description":"Analyze HCC categories for a set of codes with hierarchy suppression.\n\nFor each code, retrieves HCC categories for the specified model/version,\nattaches RAF weights, then applies CMS hierarchy rules to determine\nwhich lower-severity categories are suppressed.\n\nReturns per-code details, active/suppressed category lists, and a\ntotal RAF score from the active (non-suppressed) categories.\n\n``total_raf_score`` is ``null`` — never a bare 0.0 — whenever the mapped categories\ncould not resolve a coefficient; ``raf_status`` / ``raf_status_detail`` say why, and\n``categories_without_coefficient`` names them. A real 0.0 (every code evaluated, none\nmaps to a category in this model) is still returned as 0.0 with ``no_hcc_mapping``.\n\n**Limits:**\n- Maximum 50 codes per request\n- Requires Pro or Enterprise tier","operationId":"batch_hcc_suppress_api_v1_batch_hcc_suppress_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchHCCSuppressRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Batch Hcc Suppress Api V1 Batch Hcc Suppress Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/billing/signup":{"post":{"tags":["billing"],"summary":"Signup","description":"Create a free account and API key.\n\nDisabled by default (``anonymous_signup_enabled=False``): this account-less,\nemail-only path is off so that a key can only be obtained by registering a user\naccount and minting one from the dashboard. Returns the API key **once** when\nenabled — it cannot be retrieved again.","operationId":"signup_api_v1_billing_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Signup Api V1 Billing Signup Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/billing/checkout":{"post":{"tags":["billing"],"summary":"Create Checkout","description":"Create a Stripe Checkout session to upgrade to Pro.","operationId":"create_checkout_api_v1_billing_checkout_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Checkout Api V1 Billing Checkout Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/billing/subscription":{"get":{"tags":["billing"],"summary":"Get Subscription","description":"Get current subscription status.","operationId":"get_subscription_api_v1_billing_subscription_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Subscription Api V1 Billing Subscription Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/billing/portal":{"post":{"tags":["billing"],"summary":"Create Portal","description":"Get a Stripe Customer Portal URL for managing subscription.","operationId":"create_portal_api_v1_billing_portal_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Portal Api V1 Billing Portal Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/billing/keys/rotate":{"post":{"tags":["billing"],"summary":"Rotate Key","description":"Rotate the current API key.\n\nCreates a new key inheriting tier/owner. The old key remains valid\nfor the grace period (default 60 minutes), then expires.\n\nReturns the new API key **once** — it cannot be retrieved again.","operationId":"rotate_key_api_v1_billing_keys_rotate_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateKeyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Rotate Key Api V1 Billing Keys Rotate Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/billing/data":{"delete":{"tags":["billing"],"summary":"Delete User Data","description":"Customer-directed deletion of the PHI this API key controls.\n\nDeletes coding traces, coding cache entries, and chart review jobs owned by this\nAPI key, and writes an immutable purge record (see ``record_data_purge``). Audit\nand disclosure ledgers are retained — see the retention note below.\n\n⚠ This is **not** a \"HIPAA right to deletion\", and it must not be described as one.\n**HIPAA gives individuals no right to erasure.** 45 CFR grants a right of access\n(§164.524), a right to request amendment (§164.526) and a right to an accounting of\ndisclosures (§164.528) — deletion is not among them. That is a GDPR concept\n(Article 17), not a HIPAA one.\n\nWhat this endpoint actually is: a **covered entity instructing its business\nassociate to delete data the business associate holds on its behalf**, which is\nordinarily how a BAA works. It is a customer action, not a patient right.\n\nConsequences for whoever maintains this:\n\n* A patient asking us directly to erase their record is **not** entitled to it under\n  HIPAA. Such a request belongs with the covered entity, which owns the designated\n  record set and decides — unless a specific BAA delegates that response to us.\n* Deleting on request is still correct when the customer directs it and no retention\n  obligation applies. But an accepted §164.526 amendment must be appended or linked,\n  **not** silently overwritten, so the historical record and its audit trail survive.\n* Retention here is deliberately per-category (chart reviews 90d, coding traces 365d,\n  cache 90d, usage events ~7y for billing/tax), not a blanket six years.\n  §164.530(j)(2)'s six years applies to *documentation required by the rule* —\n  policies, communications, actions, activities, designations — not to every patient\n  record or coding transaction. Do not \"simplify\" these into one six-year default.","operationId":"delete_user_data_api_v1_billing_data_delete","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete User Data Api V1 Billing Data Delete"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/billing/webhooks/stripe":{"post":{"tags":["billing"],"summary":"Stripe Webhook","description":"Handle Stripe webhook events.\n\nEvents handled:\n- checkout.session.completed → upgrade key to Pro\n- customer.subscription.deleted → downgrade key to Free\n- customer.subscription.updated → sync status","operationId":"stripe_webhook_api_v1_billing_webhooks_stripe_post","parameters":[{"name":"stripe-signature","in":"header","required":true,"schema":{"type":"string","title":"Stripe-Signature"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"},"title":"Response Stripe Webhook Api V1 Billing Webhooks Stripe Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/billing/usage/flush":{"post":{"tags":["billing"],"summary":"Flush Metered Usage","description":"Report all unreported metered usage events for the calling key.\n\nRoutes to the correct billing provider based on the org's\n``billing_provider`` field (Stripe / AWS Marketplace / Azure Marketplace).\nIdempotent: events already reported (``reported_to_stripe_at IS NOT NULL``)\nare skipped, and each provider-specific path uses event id as the\nidempotency key so partial failures + retries do not double-charge.","operationId":"flush_metered_usage_api_v1_billing_usage_flush_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Flush Metered Usage Api V1 Billing Usage Flush Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/billing/usage/preview":{"get":{"tags":["billing"],"summary":"Preview Invoice","description":"Return Stripe's preview of the calling key's upcoming invoice.","operationId":"preview_invoice_api_v1_billing_usage_preview_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Preview Invoice Api V1 Billing Usage Preview Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/billing/pmpm/contracts":{"post":{"tags":["billing"],"summary":"Create Pmpm Contract","description":"Register a PMPM contract for the calling org.","operationId":"create_pmpm_contract_api_v1_billing_pmpm_contracts_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePMPMContractRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Pmpm Contract Api V1 Billing Pmpm Contracts Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"get":{"tags":["billing"],"summary":"List Pmpm Contracts","operationId":"list_pmpm_contracts_api_v1_billing_pmpm_contracts_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Pmpm Contracts Api V1 Billing Pmpm Contracts Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/billing/pmpm/contracts/{contract_id}/members":{"post":{"tags":["billing"],"summary":"Report Member Count","description":"Report the actual covered-member count for a billing period.\n\nUsed by the PMPM dispatcher to compute Stripe invoice quantity.\nIdempotent on (contract_id, period_year, period_month).","operationId":"report_member_count_api_v1_billing_pmpm_contracts__contract_id__members_post","parameters":[{"name":"contract_id","in":"path","required":true,"schema":{"type":"string","title":"Contract Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportMembersRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Report Member Count Api V1 Billing Pmpm Contracts  Contract Id  Members Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/billing/pmpm/contracts/{contract_id}/invoice":{"post":{"tags":["billing"],"summary":"Generate Pmpm Invoice","description":"Generate the Stripe invoice item for a PMPM contract period.\n\nPosts a single Stripe invoice item:\n    unit_amount = pmpm_rate_cents\n    quantity    = members_covered\nStripe collects + finalizes per the customer's billing cycle.\n\nInvoices the given ``period_year``/``period_month`` (defaults to the latest reported\nperiod). **Idempotent**: the Stripe idempotency key is derived from (contract, period),\nso a double POST for the same period never creates a second invoice item.","operationId":"generate_pmpm_invoice_api_v1_billing_pmpm_contracts__contract_id__invoice_post","parameters":[{"name":"contract_id","in":"path","required":true,"schema":{"type":"string","title":"Contract Id"}},{"name":"period_year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":2025},{"type":"null"}],"title":"Period Year"}},{"name":"period_month","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":12,"minimum":1},{"type":"null"}],"title":"Period Month"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Generate Pmpm Invoice Api V1 Billing Pmpm Contracts  Contract Id  Invoice Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/chart-review/upload":{"post":{"tags":["chart-review"],"summary":"Upload Chart","description":"Upload a medical chart for AI-powered review and ICD-10 coding.\n\nAccepts PDF, DOCX, TXT, RTF, CSV, XLSX, XLS, XML (C-CDA), JSON (FHIR),\nHL7v2, PNG, JPG, TIFF, BMP, HEIC, and WEBP files. Returns a job_id to poll.\n\n**Requires Pro or Enterprise tier.**","operationId":"upload_chart_api_v1_chart_review_upload_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_chart_api_v1_chart_review_upload_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreatedResponse"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/chart-review/jobs":{"get":{"tags":["chart-review"],"summary":"List Chart Review Jobs","description":"List chart review jobs for the authenticated API key.","operationId":"list_chart_review_jobs_api_v1_chart_review_jobs_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Chart Review Jobs Api V1 Chart Review Jobs Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/chart-review/{job_id}":{"get":{"tags":["chart-review"],"summary":"Get Chart Review Status","description":"Get chart review job status and results.\n\nWhile processing, returns status and progress. When complete, returns\nthe full structured review with ICD-10 codes.","operationId":"get_chart_review_status_api_v1_chart_review__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Chart Review Status Api V1 Chart Review  Job Id  Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/auth/register":{"post":{"tags":["auth"],"summary":"Register","description":"Register a new account with email + password.","operationId":"register_api_v1_auth_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Register Api V1 Auth Register Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/auth/login":{"post":{"tags":["auth"],"summary":"Login","description":"Log in with email + password.","operationId":"login_api_v1_auth_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Login Api V1 Auth Login Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/auth/logout":{"post":{"tags":["auth"],"summary":"Logout","description":"Log out — clear cookies, invalidate the refresh token AND the live access token.\n\nLogout is account-wide: `user_accounts` holds exactly one refresh token, so there is\nno per-device session to end separately. Before 2026-09-24 the access JWT stayed\nvalid for up to 15 minutes after logout; `end_sessions` now sets the revocation\ncutoff so it dies with the refresh token.","operationId":"logout_api_v1_auth_logout_post","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Logout Api V1 Auth Logout Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/auth/refresh":{"post":{"tags":["auth"],"summary":"Refresh","description":"Refresh access token using the refresh cookie.","operationId":"refresh_api_v1_auth_refresh_post","parameters":[{"name":"refresh_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refresh Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Refresh Api V1 Auth Refresh Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/auth/me":{"get":{"tags":["auth"],"summary":"Get Me","description":"Get current user profile.","operationId":"get_me_api_v1_auth_me_get","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Me Api V1 Auth Me Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"patch":{"tags":["auth"],"summary":"Update Me","description":"Update display name.","operationId":"update_me_api_v1_auth_me_patch","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProfileRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Update Me Api V1 Auth Me Patch"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"delete":{"tags":["auth"],"summary":"Delete Me","description":"Full account deletion — cancels Stripe and erases keys, traces, cache, chart\njobs, coding sessions, and org memberships.","operationId":"delete_me_api_v1_auth_me_delete","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Me Api V1 Auth Me Delete"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/auth/change-password":{"post":{"tags":["auth"],"summary":"Change Password","description":"Change password — requires current password.","operationId":"change_password_api_v1_auth_change_password_post","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangePasswordRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Change Password Api V1 Auth Change Password Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/auth/forgot-password":{"post":{"tags":["auth"],"summary":"Forgot Password","description":"Send password reset email. Always returns 200 to prevent enumeration.","operationId":"forgot_password_api_v1_auth_forgot_password_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForgotPasswordRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Forgot Password Api V1 Auth Forgot Password Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/auth/reset-password":{"post":{"tags":["auth"],"summary":"Reset Password","description":"Reset password using token from email.","operationId":"reset_password_api_v1_auth_reset_password_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Reset Password Api V1 Auth Reset Password Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/auth/verify-email":{"post":{"tags":["auth"],"summary":"Verify Email","description":"Verify email address with token.","operationId":"verify_email_api_v1_auth_verify_email_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyEmailRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Verify Email Api V1 Auth Verify Email Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/auth/resend-verification":{"post":{"tags":["auth"],"summary":"Resend Verification","description":"Resend verification email.","operationId":"resend_verification_api_v1_auth_resend_verification_post","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Resend Verification Api V1 Auth Resend Verification Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/auth/google":{"get":{"tags":["auth"],"summary":"Google Login","description":"Redirect to Google OAuth consent screen.","operationId":"google_login_api_v1_auth_google_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Google Login Api V1 Auth Google Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/auth/google/callback":{"get":{"tags":["auth"],"summary":"Google Callback","description":"Handle Google OAuth callback — create/link user, set cookies, redirect.","operationId":"google_callback_api_v1_auth_google_callback_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Google Callback Api V1 Auth Google Callback Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/auth/microsoft":{"get":{"tags":["auth"],"summary":"Microsoft Login","description":"Redirect to Microsoft OAuth consent screen.","operationId":"microsoft_login_api_v1_auth_microsoft_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Microsoft Login Api V1 Auth Microsoft Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/auth/microsoft/callback":{"get":{"tags":["auth"],"summary":"Microsoft Callback","description":"Handle Microsoft OAuth callback — create/link user, set cookies, redirect.","operationId":"microsoft_callback_api_v1_auth_microsoft_callback_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Microsoft Callback Api V1 Auth Microsoft Callback Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/auth/mfa/enroll":{"post":{"tags":["auth"],"summary":"Mfa Enroll","description":"Begin enrolment: mint a secret and return the provisioning URI.\n\nThis does NOT enable MFA. The secret is stored but `mfa_enabled` stays false until\n/mfa/verify proves the user can actually generate a code — otherwise starting\nenrolment and then losing the authenticator app would lock the account out.\n\nThe provisioning URI contains the shared secret, so it is returned exactly once here\nand is never written to a log or an audit `detail`.","operationId":"mfa_enroll_api_v1_auth_mfa_enroll_post","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Mfa Enroll Api V1 Auth Mfa Enroll Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/auth/mfa/verify":{"post":{"tags":["auth"],"summary":"Mfa Verify","description":"Finish enrolment: prove a code works, then enable MFA and issue backup codes.","operationId":"mfa_verify_api_v1_auth_mfa_verify_post","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MFAVerifyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Mfa Verify Api V1 Auth Mfa Verify Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/auth/mfa/disable":{"post":{"tags":["auth"],"summary":"Mfa Disable","description":"Turn MFA off. Requires BOTH the password and a current code.\n\nRemoving a factor is exactly when to demand the factor being removed: a stolen session\ncookie should not be enough to strip the account back to a password.","operationId":"mfa_disable_api_v1_auth_mfa_disable_post","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MFADisableRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Mfa Disable Api V1 Auth Mfa Disable Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/auth/mfa/status":{"get":{"tags":["auth"],"summary":"Mfa Status","operationId":"mfa_status_api_v1_auth_mfa_status_get","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Mfa Status Api V1 Auth Mfa Status Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/keys":{"get":{"tags":["keys"],"summary":"List Keys","description":"List API keys for the current user (scope=mine, default) or, for an org owner/admin,\nthe org's keys too (scope=org — surfaces provisioned marketplace / GPT-OAuth keys).","operationId":"list_keys_api_v1_keys_get","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","pattern":"^(mine|org)$","default":"mine","title":"Scope"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Keys Api V1 Keys Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"post":{"tags":["keys"],"summary":"Create Key","description":"Create a new API key. Returns the full key once — it cannot be retrieved again.","operationId":"create_key_api_v1_keys_post","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKeyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Key Api V1 Keys Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/keys/{key_id}":{"delete":{"tags":["keys"],"summary":"Revoke Key","description":"Revoke an API key (own key, or an org key if scope=org and the user owns/admins it).","operationId":"revoke_key_api_v1_keys__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","pattern":"^(mine|org)$","default":"mine","title":"Scope"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Revoke Key Api V1 Keys  Key Id  Delete"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/keys/{key_id}/rotate":{"post":{"tags":["keys"],"summary":"Rotate Key","description":"Rotate an API key with a grace period (own key, or an org key the user owns/admins).","operationId":"rotate_key_api_v1_keys__key_id__rotate_post","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","pattern":"^(mine|org)$","default":"mine","title":"Scope"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateKeyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Rotate Key Api V1 Keys  Key Id  Rotate Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/orgs":{"post":{"tags":["orgs"],"summary":"Create Org","description":"Create a new organization. Caller is automatically added as owner.","operationId":"create_org_api_v1_orgs_post","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrgRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgEnvelope"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"get":{"tags":["orgs"],"summary":"List My Orgs","description":"List every org the calling user is a member of.","operationId":"list_my_orgs_api_v1_orgs_get","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgListResponse"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/orgs/{slug}":{"get":{"tags":["orgs"],"summary":"Get Org","operationId":"get_org_api_v1_orgs__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgEnvelope"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"patch":{"tags":["orgs"],"summary":"Update Org","operationId":"update_org_api_v1_orgs__slug__patch","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrgRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgEnvelope"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/orgs/{slug}/members":{"get":{"tags":["orgs"],"summary":"List Members","operationId":"list_members_api_v1_orgs__slug__members_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Members Api V1 Orgs  Slug  Members Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"post":{"tags":["orgs"],"summary":"Invite Member","operationId":"invite_member_api_v1_orgs__slug__members_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteMemberRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Invite Member Api V1 Orgs  Slug  Members Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/orgs/{slug}/members/{user_id}":{"patch":{"tags":["orgs"],"summary":"Update Member Role","operationId":"update_member_role_api_v1_orgs__slug__members__user_id__patch","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRoleRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Update Member Role Api V1 Orgs  Slug  Members  User Id  Patch"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"delete":{"tags":["orgs"],"summary":"Remove Member","operationId":"remove_member_api_v1_orgs__slug__members__user_id__delete","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/orgs/{slug}/data":{"delete":{"tags":["orgs"],"summary":"Purge Org Data","description":"Destroy every row of PHI this organization holds with us. Owner only.\n\nThis is the \"return or destroy\" duty a business associate owes at termination\n(§164.504(e)(2)(ii)(J)), exercised by the customer's own owner. It is deliberately not a\n\"delete the organization\" call: the org, its people, its API keys, its billing history and\nthe three ledgers (``audit_logs``, ``phi_access_log``, ``data_purge_records``) survive, so\nthe customer can still read the accounting of disclosures and the proof that this purge\nhappened. What goes is listed in ``app.core.phi_purge.ORG_PURGE_TABLE_ORDER``.\n\nFail-closed: the deletes and the purge record share one transaction. Any failure rolls\nthe whole thing back and the request is retryable. On success the org's PHI activation\nis revoked (``phi_access_approved_at = NULL``) so no new PHI lands until it is\ndeliberately re-onboarded.","operationId":"purge_org_data_api_v1_orgs__slug__data_delete","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurgeOrgDataRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Purge Org Data Api V1 Orgs  Slug  Data Delete"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/orgs/{slug}/domains":{"post":{"tags":["orgs"],"summary":"Register Domain","description":"Register a vanity hostname for white-label branding (admin+).\n\nReturns a DNS TXT verification token. NO DNS/cert binding happens here — the\nmapping is inert until ops verifies the TXT record (sets verified_at) and\nwires the host to ingress with a managed cert. Production hosts are refused.","operationId":"register_domain_api_v1_orgs__slug__domains_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterDomainRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterDomainResponse"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"get":{"tags":["orgs"],"summary":"List Domains","operationId":"list_domains_api_v1_orgs__slug__domains_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainListResponse"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/orgs/{slug}/domains/{domain_id}":{"delete":{"tags":["orgs"],"summary":"Remove Domain","operationId":"remove_domain_api_v1_orgs__slug__domains__domain_id__delete","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"domain_id","in":"path","required":true,"schema":{"type":"string","title":"Domain Id"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/orgs/{slug}/scim/token":{"post":{"tags":["orgs"],"summary":"Generate Scim Token","description":"Generate (or rotate) this org's SCIM bearer token. Admin+; shown once.\n\nConfigure the IdP's SCIM connector with this token and the ``/scim/v2`` base\nURL. We store only the SHA-256 hash; rotating issues a new token and\ninvalidates the old one.","operationId":"generate_scim_token_api_v1_orgs__slug__scim_token_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScimTokenResponse"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/auth/sso/{slug}/login":{"get":{"tags":["sso"],"summary":"Sso Login","description":"Begin OIDC authorization-code flow for the given org.","operationId":"sso_login_api_v1_auth_sso__slug__login_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/auth/sso/{slug}/callback":{"get":{"tags":["sso"],"summary":"Sso Callback","description":"Handle IdP redirect: exchange code for token, match user, issue JWT cookie.","operationId":"sso_callback_api_v1_auth_sso__slug__callback_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"}},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"}},{"name":"error","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/auth/saml/{slug}/metadata":{"get":{"tags":["saml"],"summary":"Saml Metadata","description":"Return this org's SP metadata XML (for the IdP admin to configure).","operationId":"saml_metadata_api_v1_auth_saml__slug__metadata_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/auth/saml/{slug}/login":{"get":{"tags":["saml"],"summary":"Saml Login","description":"Begin SP-initiated SAML login: redirect to the IdP's SSO URL.","operationId":"saml_login_api_v1_auth_saml__slug__login_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/auth/saml/{slug}/acs":{"post":{"tags":["saml"],"summary":"Saml Acs","description":"Assertion Consumer Service: validate the IdP's SAML response, log the user in.","operationId":"saml_acs_api_v1_auth_saml__slug__acs_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/marketplace/aws/register":{"post":{"tags":["marketplace"],"summary":"Aws Register","description":"Exchange the AWS Marketplace registration token for a customer record.","operationId":"aws_register_api_v1_marketplace_aws_register_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_aws_register_api_v1_marketplace_aws_register_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Aws Register Api V1 Marketplace Aws Register Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/marketplace/aws/sns":{"post":{"tags":["marketplace"],"summary":"Aws Sns","description":"Receive SNS lifecycle notifications.\n\nThe message body is not trusted to set entitlements: we check the topic\nARN, restrict SubscribeURL fetches to AWS hosts (SSRF), and re-derive the\norg's tier from authoritative AWS entitlements rather than the message.","operationId":"aws_sns_api_v1_marketplace_aws_sns_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Aws Sns Api V1 Marketplace Aws Sns Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/marketplace/azure/landing":{"get":{"tags":["marketplace"],"summary":"Azure Landing","description":"Resolve an Azure Marketplace landing-page token to a subscription.","operationId":"azure_landing_api_v1_marketplace_azure_landing_get","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string","description":"x-ms-marketplace-token from Azure","title":"Token"},"description":"x-ms-marketplace-token from Azure"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Azure Landing Api V1 Marketplace Azure Landing Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/marketplace/azure/webhook":{"post":{"tags":["marketplace"],"summary":"Azure Webhook","description":"Handle Azure marketplace lifecycle events.","operationId":"azure_webhook_api_v1_marketplace_azure_webhook_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AzureWebhook"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Azure Webhook Api V1 Marketplace Azure Webhook Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/resellers/{slug}/customers":{"post":{"tags":["resellers"],"summary":"Provision Customer","description":"Provision a new customer sub-account under this reseller.","operationId":"provision_customer_api_v1_resellers__slug__customers_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionCustomerRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionCustomerResponse"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"get":{"tags":["resellers"],"summary":"List Customers","description":"List this reseller's live customer sub-accounts.","operationId":"list_customers_api_v1_resellers__slug__customers_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerListResponse"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/resellers/{slug}/customers/{customer_org_id}":{"patch":{"tags":["resellers"],"summary":"Update Customer Link","description":"Update a child's contract terms or lifecycle status.","operationId":"update_customer_link_api_v1_resellers__slug__customers__customer_org_id__patch","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"customer_org_id","in":"path","required":true,"schema":{"type":"string","title":"Customer Org Id"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLinkRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLinkResponse"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/resellers/{slug}/billing/flush":{"post":{"tags":["resellers"],"summary":"Flush Consolidated","description":"Bill every reseller-billed child's outstanding usage against the reseller.","operationId":"flush_consolidated_api_v1_resellers__slug__billing_flush_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlushResponse"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/resellers/{slug}/commissions":{"get":{"tags":["resellers"],"summary":"List Commissions","description":"Read the append-only commission (rev-share) ledger for this reseller.","operationId":"list_commissions_api_v1_resellers__slug__commissions_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionsResponse"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/webhooks":{"post":{"tags":["webhooks"],"summary":"Create Webhook","operationId":"create_webhook_api_v1_webhooks_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Webhook Api V1 Webhooks Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"get":{"tags":["webhooks"],"summary":"List Webhooks","operationId":"list_webhooks_api_v1_webhooks_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Webhooks Api V1 Webhooks Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/webhooks/{sub_id}":{"get":{"tags":["webhooks"],"summary":"Get Webhook","operationId":"get_webhook_api_v1_webhooks__sub_id__get","parameters":[{"name":"sub_id","in":"path","required":true,"schema":{"type":"string","title":"Sub Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Webhook Api V1 Webhooks  Sub Id  Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"patch":{"tags":["webhooks"],"summary":"Update Webhook","operationId":"update_webhook_api_v1_webhooks__sub_id__patch","parameters":[{"name":"sub_id","in":"path","required":true,"schema":{"type":"string","title":"Sub Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Update Webhook Api V1 Webhooks  Sub Id  Patch"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"delete":{"tags":["webhooks"],"summary":"Delete Webhook","operationId":"delete_webhook_api_v1_webhooks__sub_id__delete","parameters":[{"name":"sub_id","in":"path","required":true,"schema":{"type":"string","title":"Sub Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/webhooks/{sub_id}/test":{"post":{"tags":["webhooks"],"summary":"Test Webhook","operationId":"test_webhook_api_v1_webhooks__sub_id__test_post","parameters":[{"name":"sub_id","in":"path","required":true,"schema":{"type":"string","title":"Sub Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Test Webhook Api V1 Webhooks  Sub Id  Test Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/webhooks/{sub_id}/deliveries":{"get":{"tags":["webhooks"],"summary":"List Deliveries","operationId":"list_deliveries_api_v1_webhooks__sub_id__deliveries_get","parameters":[{"name":"sub_id","in":"path","required":true,"schema":{"type":"string","title":"Sub Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Deliveries Api V1 Webhooks  Sub Id  Deliveries Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/audit/export":{"get":{"tags":["audit"],"summary":"Export Audit Log","description":"Stream the calling org's audit log entries in the requested format.","operationId":"export_audit_log_api_v1_audit_export_get","parameters":[{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Until"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(csv|fhir-auditevent)$","default":"csv","title":"Format"}},{"name":"source","in":"query","required":false,"schema":{"type":"string","pattern":"^(audit|disclosures)$","description":"`audit` (default) = operational audit_logs. `disclosures` = the HIPAA §164.528 accounting-of-disclosures ledger (phi_access_log), filterable by upstream_tenant_id + resource_id; pro and enterprise tiers.","default":"audit","title":"Source"},"description":"`audit` (default) = operational audit_logs. `disclosures` = the HIPAA §164.528 accounting-of-disclosures ledger (phi_access_log), filterable by upstream_tenant_id + resource_id; pro and enterprise tiers."},{"name":"upstream_tenant_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"description":"disclosures only: filter to one delegated upstream tenant id.","title":"Upstream Tenant Id"},"description":"disclosures only: filter to one delegated upstream tenant id."},{"name":"resource_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"description":"disclosures only: filter to one subject/patient handle (resource_id).","title":"Resource Id"},"description":"disclosures only: filter to one subject/patient handle (resource_id)."},{"name":"view","in":"query","required":false,"schema":{"type":"string","pattern":"^(rows|breakdown)$","description":"`rows` (default) streams individual entries. `breakdown` (disclosures only) returns an aggregated per-tenant / per-patient §164.528 accounting summary.","default":"rows","title":"View"},"description":"`rows` (default) streams individual entries. `breakdown` (disclosures only) returns an aggregated per-tenant / per-patient §164.528 accounting summary."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"default":1000,"title":"Page Size"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/legal/baa/document":{"get":{"tags":["legal"],"summary":"Baa Document","description":"The BAA text this org would accept now, with its SHA-256 to echo on /accept.","operationId":"baa_document_api_v1_legal_baa_document_get","parameters":[{"name":"org_slug","in":"query","required":true,"schema":{"type":"string","title":"Org Slug"}},{"name":"capacity","in":"query","required":false,"schema":{"type":"string","default":"covered_entity","title":"Capacity"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Baa Document Api V1 Legal Baa Document Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/legal/baa/accept":{"post":{"tags":["legal"],"summary":"Accept Baa","description":"Record a deliberate acceptance of the offered BAA. Owner or admin, with authority.","operationId":"accept_baa_api_v1_legal_baa_accept_post","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BAAAcceptRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Accept Baa Api V1 Legal Baa Accept Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/legal/baa/status":{"get":{"tags":["legal"],"summary":"Baa Status","description":"Whether the org has a BAA on file, and what the PHI gate will decide for it.","operationId":"baa_status_api_v1_legal_baa_status_get","parameters":[{"name":"org_slug","in":"query","required":true,"schema":{"type":"string","title":"Org Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Baa Status Api V1 Legal Baa Status Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/incidents/breach-report":{"post":{"tags":["incidents"],"summary":"Report Breach","description":"File a HIPAA breach/security-incident report for an organization. Owner-only.","operationId":"report_breach_api_v1_incidents_breach_report_post","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BreachReportRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Report Breach Api V1 Incidents Breach Report Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/orgs/{slug}/meat-profiles":{"post":{"tags":["meat-profiles"],"summary":"Create Profile","operationId":"create_profile_api_v1_orgs__slug__meat_profiles_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProfileRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Profile Api V1 Orgs  Slug  Meat Profiles Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"get":{"tags":["meat-profiles"],"summary":"List Profiles","operationId":"list_profiles_api_v1_orgs__slug__meat_profiles_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Profiles Api V1 Orgs  Slug  Meat Profiles Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/orgs/{slug}/meat-profiles/{name}":{"get":{"tags":["meat-profiles"],"summary":"Get Profile","operationId":"get_profile_api_v1_orgs__slug__meat_profiles__name__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Profile Api V1 Orgs  Slug  Meat Profiles  Name  Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"patch":{"tags":["meat-profiles"],"summary":"Update Profile","operationId":"update_profile_api_v1_orgs__slug__meat_profiles__name__patch","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMeatProfileRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Update Profile Api V1 Orgs  Slug  Meat Profiles  Name  Patch"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"delete":{"tags":["meat-profiles"],"summary":"Delete Profile","operationId":"delete_profile_api_v1_orgs__slug__meat_profiles__name__delete","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/orgs/{slug}/meat-profiles/{name}/set-default":{"post":{"tags":["meat-profiles"],"summary":"Set Default","operationId":"set_default_api_v1_orgs__slug__meat_profiles__name__set_default_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Set Default Api V1 Orgs  Slug  Meat Profiles  Name  Set Default Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/orgs/{slug}/coding-policies":{"post":{"tags":["coding-policies"],"summary":"Create Policy","operationId":"create_policy_api_v1_orgs__slug__coding_policies_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePolicyRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Policy Api V1 Orgs  Slug  Coding Policies Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"get":{"tags":["coding-policies"],"summary":"List Policies","operationId":"list_policies_api_v1_orgs__slug__coding_policies_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Policies Api V1 Orgs  Slug  Coding Policies Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/orgs/{slug}/coding-policies/{name}":{"get":{"tags":["coding-policies"],"summary":"Get Policy","operationId":"get_policy_api_v1_orgs__slug__coding_policies__name__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Policy Api V1 Orgs  Slug  Coding Policies  Name  Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"patch":{"tags":["coding-policies"],"summary":"Update Policy","operationId":"update_policy_api_v1_orgs__slug__coding_policies__name__patch","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePolicyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Update Policy Api V1 Orgs  Slug  Coding Policies  Name  Patch"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"delete":{"tags":["coding-policies"],"summary":"Delete Policy","operationId":"delete_policy_api_v1_orgs__slug__coding_policies__name__delete","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/orgs/{slug}/coding-policies/{name}/set-default":{"post":{"tags":["coding-policies"],"summary":"Set Default","operationId":"set_default_api_v1_orgs__slug__coding_policies__name__set_default_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Set Default Api V1 Orgs  Slug  Coding Policies  Name  Set Default Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/benchmark":{"get":{"tags":["benchmark"],"summary":"Get Benchmark","description":"Return the most recent accuracy benchmark results.\n\nPublic — no auth — so procurement teams can sanity-check our accuracy claims\nbefore engaging. When no benchmark has been published (or the results file is\nabsent from the deployed image), returns an explicit ``not_yet_published`` status\nwith 200 rather than a 404 — a missing file is a normal state, not an error.","operationId":"get_benchmark_api_v1_benchmark_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Benchmark Api V1 Benchmark Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/demo/cases":{"get":{"tags":["demo"],"summary":"List Demo Cases","description":"The synthetic demonstration corpus.\n\nPublic — no auth — for the same reason ``/api/v1/benchmark`` is: it is a static read of\nfabricated content, and a prospect evaluating the product should be able to see what the\ndemo will run before they hold a key.","operationId":"list_demo_cases_api_v1_demo_cases_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response List Demo Cases Api V1 Demo Cases Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/demo/cases/{case_id}":{"get":{"tags":["demo"],"summary":"Get Demo Case","description":"One synthetic chart by id. Public, static — see :func:`list_demo_cases`.","operationId":"get_demo_case_api_v1_demo_cases__case_id__get","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","title":"Case Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Demo Case Api V1 Demo Cases  Case Id  Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/demo/code":{"post":{"tags":["demo"],"summary":"Code Demo Case","description":"Run one synthetic chart through the production coding pipeline.\n\nSame engine as ``POST /api/v1/code`` — the same ``CodingAgentService``, the same\nverification passes — so what a prospect sees here is what they would buy.\n\nThree deliberate differences from ``/code``, each of which reads as a missing gate until\nyou know what this endpoint can and cannot receive:\n\n* **No ``ai_coding_enabled`` check.** That flag gates the *capability being sold*: coding\n  text the customer supplies. This endpoint cannot code customer text at all, so gating it\n  on the paid flag would make the free tier undemonstrable, which is the whole problem.\n* **No BAA gate.** ``/code`` is BAA-gated because it ingests PHI. This corpus is fabricated\n  and the request carries no text, so there is no PHI to be a business associate for.\n  Requiring a BAA to look at fictional charts would invert the policy it enforces.\n* **No PHI audit event and no trace persistence.** ``/code`` writes a\n  ``PHI_CREATE``/``phi_accessed=True`` audit row that feeds HIPAA accounting-of-disclosures.\n  Writing one here would file records that contain no PHI into the disclosure trail and\n  make it less useful, not more. The usage meter still records the call.","operationId":"code_demo_case_api_v1_demo_code_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoCodeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Code Demo Case Api V1 Demo Code Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/api/v1/payers":{"get":{"tags":["payers"],"summary":"List Payers","description":"Return the supported payers, ordered by name.","operationId":"list_payers_api_v1_payers_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Payers Api V1 Payers Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/cpt/codes":{"get":{"tags":["cpt"],"summary":"List Cpt Codes","description":"List CPT codes. Descriptions are present only if the AMA license is loaded.","operationId":"list_cpt_codes_api_v1_cpt_codes_get","parameters":[{"name":"ai_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Ai Only"}},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Cpt Codes Api V1 Cpt Codes Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/api/v1/cpt/codes/{code}":{"get":{"tags":["cpt"],"summary":"Get Cpt Code","operationId":"get_cpt_code_api_v1_cpt_codes__code__get","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Cpt Code Api V1 Cpt Codes  Code  Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/api/v1/cpt/submit":{"post":{"tags":["cpt"],"summary":"Submit Cpt","description":"Validate that an AI-augmented CPT submission carries algorithm metadata.\n\nReturns 400 ``missing_ai_metadata`` if the requested code requires\nalgorithm metadata but ``ai_metadata`` is missing or incomplete.","operationId":"submit_cpt_api_v1_cpt_submit_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitCPTRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Submit Cpt Api V1 Cpt Submit Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/api/v1/cpt/validate":{"post":{"tags":["cpt"],"summary":"Validate Cpt Claim","description":"Scrub a claim against the CMS edit tables — deterministic, no LLM, no chart text.\n\nRuns eleven deterministic engines (code existence, HCPCS Level II existence/validity/\ncoverage, date-of-service billability, PFS payment status, add-on primaries, NCCI PTP\nbundling, MUE unit ceilings, global periods, modifier applicability, code-category\nappropriateness, same-day E/M) and returns findings plus suggested fixes and Medicare\nRVU pricing context.\n\n**Nothing is auto-corrected.** `suggested_fixes` is a separate list, and each fix carries\n`requires_documentation`: fixes that merely restate the claim (drop an impossible\nmodifier, cap units at an absolute ceiling) are safe to apply mechanically, while fixes\nthat assert a clinical fact (append 59, append 25) are not, and must not be applied\nwithout the note in front of a human.\n\n**Read `engines_skipped` before trusting a clean result.** An engine whose CMS table is\nabsent, or whose loaded snapshot does not cover the date of service, records itself\nthere and emits an INFO finding — a claim with no findings because nobody looked is not\na clean claim.\n\n**Requires Pro or Enterprise tier.**","operationId":"validate_cpt_claim_api_v1_cpt_validate_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CptValidateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Validate Cpt Claim Api V1 Cpt Validate Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/api/v1/cpt/search":{"get":{"tags":["cpt"],"summary":"Search Cpt Codes","description":"Find CPT codes matching procedure text — deterministic, no LLM.\n\nHybrid full-text + trigram retrieval over the CPT corpus, with surgeon-shorthand\nexpansion (\"lap chole\" → laparoscopic cholecystectomy), axis-aware rescoring, and family\nexpansion so with/without and approach variants are visible rather than pruned.\n\n**Every returned code is verified to exist in the CPT code set for the year.** This is\nthe same retriever the chart→CPT pipeline uses, and it is the only component that can\nproduce a CPT code at all.\n\n**Scores are RETRIEVAL scores, not confidence.** They say how well the query's wording\nmatched a code's phrasings — nothing about whether the code is billable, correctly\nmodified, or supported by documentation. Use `/cpt/validate` for that.\n\n⚠ **`corpus_ready: false` means the answer is empty because the corpus is unbuilt, not\nbecause nothing matched.** Those are different facts and the response distinguishes them.\n\n⚠ Descriptors are **not** returned: they are AMA-licensed, and this response is\nunmetered reference output. Use `GET /cpt/codes/{code}`, which gates descriptor text on\n`AMA_CPT_LICENSE_KEY`.\n\n**Requires Pro or Enterprise tier.**","operationId":"search_cpt_codes_api_v1_cpt_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":300,"description":"Procedure text to match","title":"Q"},"description":"Procedure text to match"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":12,"title":"Limit"}},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":2000},{"type":"null"}],"description":"CPT CALENDAR year","title":"Year"},"description":"CPT CALENDAR year"},{"name":"include_category_ii","in":"query","required":false,"schema":{"type":"boolean","description":"Include Category II performance-measurement tracking codes. Excluded by default: they carry no payment and are a different kind of answer to a procedure question, not a near miss.","default":false,"title":"Include Category Ii"},"description":"Include Category II performance-measurement tracking codes. Excluded by default: they carry no payment and are a different kind of answer to a procedure question, not a near miss."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Search Cpt Codes Api V1 Cpt Search Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/api/v1/cpt/em-level":{"post":{"tags":["cpt"],"summary":"Compute Em Level Endpoint","description":"Compute an E/M level deterministically, with a citeable worksheet.\n\nAn LLM reads the note and reports WHAT IT SAYS — how many problems, which data, what\nmanagement risk, how many documented minutes — each with a verbatim quote. The\narithmetic that turns those into 99213 rather than 99214 is a pure function and never\ntouches a model.\n\n**The worksheet is the product.** Every element carries the rule that decided it and the\nspans it rested on, and the losing path is reported too: \"the time basis supports 99215\nbut the MDM only supports 99214\" is a fact a coder needs, and a calculator that reports\nonly its winner destroys it.\n\n⚠ **A quote that is not in the note is discarded**, not trusted. An observation with no\nsurviving quote does not count toward any element.\n\n**Requires Pro or Enterprise tier, an executed BAA, and PHI activation.**","operationId":"compute_em_level_endpoint_api_v1_cpt_em_level_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmLevelRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Compute Em Level Endpoint Api V1 Cpt Em Level Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/api/v1/cpt/code":{"post":{"tags":["cpt"],"summary":"Code Chart To Cpt","description":"Code the procedures documented in a chart, then scrub the resulting claim.\n\nFive stages: LLM procedure-mention extraction → deterministic retrieval → batched LLM\ndisambiguation → deterministic modifier proposal → deterministic verification.\n\n⚠ **Neither LLM call can produce a code.** Stage 1 raises on a code-shaped token; Stage 3\nchooses from the list retrieval built and verified against the code set. The codes this\nendpoint can emit are exactly the codes retrieval found — that is a property of the\nwiring, not of the prompts.\n\n⚠ **Read `result_state` before `lines`.** An empty line list means one of several very\ndifferent things, and `documentation_gap` (a chart problem you can act on) is not\n`retrieval_unavailable` (our corpus is unbuilt).\n\n⚠ **`candidate_modifiers` are prompts, not decisions.** A modifier under\n`applied_modifiers` follows from a documented axis and a CMS indicator. One under\n`candidate_modifiers` is permitted by the fee schedule but needs the note to support it,\nand the verification below was run WITHOUT it applied. **59 and 25 are never proposed at\nall** — they assert clinical facts only the documentation establishes.\n\n**Requires Pro or Enterprise tier, an executed BAA, and PHI activation.**","operationId":"code_chart_to_cpt_api_v1_cpt_code_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CptCodeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Code Chart To Cpt Api V1 Cpt Code Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/api/v1/inpatient/code":{"post":{"tags":["inpatient"],"summary":"Code Inpatient","description":"Code the ICD-10-PCS procedures documented in an inpatient chart.\n\nStage 1 (LLM) extracts procedure mentions in the chart's words; Stage 2 walks CMS's index\nand code tables deterministically; Stage 3 (LLM) chooses ONLY among legal values when the\nchart's words do not settle a character; Stage 4 verifies against the discharge-date\nedition and the PCS guidelines. **Neither LLM call can produce a code** — codes come\nfrom the tables. Anything the chart does not settle is returned under ``needs_review``\nwith the legal menu, never guessed.\n\nSupply ``principal_dx`` (+ ``secondary_dx``, all with POA) and the encounter fields to\nalso receive the MS-DRG and a principal procedure chosen by the CMS grouper; without them\n``principal_procedure.basis`` is ``first_definitive_proposal``.\n\n**Requires Pro or Enterprise tier, an executed BAA, and PHI activation.**","operationId":"code_inpatient_api_v1_inpatient_code_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InpatientCodeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Code Inpatient Api V1 Inpatient Code Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/api/v1/drg/group":{"post":{"tags":["drg"],"summary":"Group Drg","description":"Group one inpatient claim with the CMS MS-DRG grouper and Medicare Code Editor.\n\nThe grouper version is chosen from the discharge date (v42.0 … v44.0) and every procedure\nis first checked against the ICD-10-PCS edition in force that day — an invalid code is a\n422 listing why, never silently grouped. Missing POA, discharge status, POA-reporting\nstatus, dates, age or sex are refused with typed 422s (``drg_poa_missing``, …).\n\n**Requires Pro or Enterprise tier, an executed BAA, and PHI activation.**","operationId":"group_drg_api_v1_drg_group_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrgGroupRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Group Drg Api V1 Drg Group Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/api/v1/members":{"post":{"tags":["members"],"summary":"Create Member","operationId":"create_member_api_v1_members_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMemberRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Member Api V1 Members Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"get":{"tags":["members"],"summary":"List Members","description":"Pagination: accepts page/page_size (storefront convention) or\nlimit/offset (legacy). limit/offset wins if both are passed.","operationId":"list_members_api_v1_members_get","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Page Size"}},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":500,"minimum":1},{"type":"null"}],"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Members Api V1 Members Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/members/{member_id}":{"get":{"tags":["members"],"summary":"Get Member","operationId":"get_member_api_v1_members__member_id__get","parameters":[{"name":"member_id","in":"path","required":true,"schema":{"type":"string","title":"Member Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Member Api V1 Members  Member Id  Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"patch":{"tags":["members"],"summary":"Update Member","operationId":"update_member_api_v1_members__member_id__patch","parameters":[{"name":"member_id","in":"path","required":true,"schema":{"type":"string","title":"Member Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMemberRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Update Member Api V1 Members  Member Id  Patch"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"delete":{"tags":["members"],"summary":"Delete Member","description":"Delete a member **and every row holding that member's PHI**.\n\nBefore 2026-09-24 this deleted the ``members`` row alone. Every dependent table is joined\nwith ``ON DELETE SET NULL`` (migrations 021/022), so the member's clinical documents, chart\njobs, recommendations and evidence spans all survived with ``member_id = NULL`` — while\nthe purge record said ``{\"members\": 1}``. The proof of destruction described one row and\nnot the patient. See ``app/core/phi_purge.py`` for the table order and why.","operationId":"delete_member_api_v1_members__member_id__delete","parameters":[{"name":"member_id","in":"path","required":true,"schema":{"type":"string","title":"Member Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Member Api V1 Members  Member Id  Delete"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/members/{member_id}/charts":{"get":{"tags":["members"],"summary":"List Member Charts","operationId":"list_member_charts_api_v1_members__member_id__charts_get","parameters":[{"name":"member_id","in":"path","required":true,"schema":{"type":"string","title":"Member Id"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Page Size"}},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":500,"minimum":1},{"type":"null"}],"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Member Charts Api V1 Members  Member Id  Charts Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/reviewer/queue":{"get":{"tags":["reviewer"],"summary":"Get Queue","description":"Pending (or filtered-status) recommendations for the calling org.\n\nPagination: accepts either page/page_size (storefront convention)\nor limit/offset (legacy). Status filter accepts either ``status``\nor ``queue_status`` for the same reason.","operationId":"get_queue_api_v1_reviewer_queue_get","parameters":[{"name":"queue_status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Queue Status"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Page Size"}},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":500,"minimum":1},{"type":"null"}],"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Queue Api V1 Reviewer Queue Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/reviewer/recommendations/{rec_id}":{"get":{"tags":["reviewer"],"summary":"Get Recommendation","operationId":"get_recommendation_api_v1_reviewer_recommendations__rec_id__get","parameters":[{"name":"rec_id","in":"path","required":true,"schema":{"type":"string","title":"Rec Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Recommendation Api V1 Reviewer Recommendations  Rec Id  Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/reviewer/recommendations/{rec_id}/accept":{"post":{"tags":["reviewer"],"summary":"Accept Recommendation","operationId":"accept_recommendation_api_v1_reviewer_recommendations__rec_id__accept_post","parameters":[{"name":"rec_id","in":"path","required":true,"schema":{"type":"string","title":"Rec Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Accept Recommendation Api V1 Reviewer Recommendations  Rec Id  Accept Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/reviewer/recommendations/{rec_id}/reject":{"post":{"tags":["reviewer"],"summary":"Reject Recommendation","operationId":"reject_recommendation_api_v1_reviewer_recommendations__rec_id__reject_post","parameters":[{"name":"rec_id","in":"path","required":true,"schema":{"type":"string","title":"Rec Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Reject Recommendation Api V1 Reviewer Recommendations  Rec Id  Reject Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/reviewer/recommendations/{rec_id}/edit":{"post":{"tags":["reviewer"],"summary":"Edit Recommendation","operationId":"edit_recommendation_api_v1_reviewer_recommendations__rec_id__edit_post","parameters":[{"name":"rec_id","in":"path","required":true,"schema":{"type":"string","title":"Rec Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Edit Recommendation Api V1 Reviewer Recommendations  Rec Id  Edit Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/reviewer/recommendations/{rec_id}/escalate":{"post":{"tags":["reviewer"],"summary":"Escalate Recommendation","operationId":"escalate_recommendation_api_v1_reviewer_recommendations__rec_id__escalate_post","parameters":[{"name":"rec_id","in":"path","required":true,"schema":{"type":"string","title":"Rec Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Escalate Recommendation Api V1 Reviewer Recommendations  Rec Id  Escalate Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/recommendations/{rec_id}":{"get":{"tags":["recommendations"],"summary":"Get Recommendation","description":"Return a single recommendation with its evidence rows.\n\nUsed by the chart-evidence viewer in the storefront. Org-scoped:\na recommendation belonging to a different org returns 404 (not 403)\nto avoid leaking the existence of cross-org rows.","operationId":"get_recommendation_api_v1_recommendations__rec_id__get","parameters":[{"name":"rec_id","in":"path","required":true,"schema":{"type":"string","title":"Rec Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Recommendation Api V1 Recommendations  Rec Id  Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/radv/recommendations/{rec_id}":{"get":{"tags":["radv"],"summary":"Get Recommendation Radv Packet","description":"The RADV packet candidate for one HCC-bearing recommendation.","operationId":"get_recommendation_radv_packet_api_v1_radv_recommendations__rec_id__get","parameters":[{"name":"rec_id","in":"path","required":true,"schema":{"type":"string","title":"Rec Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Recommendation Radv Packet Api V1 Radv Recommendations  Rec Id  Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/radv/charts/{chart_id}":{"get":{"tags":["radv"],"summary":"Get Chart Radv Packets","description":"Every HCC-bearing recommendation of one chart, one packet each.","operationId":"get_chart_radv_packets_api_v1_radv_charts__chart_id__get","parameters":[{"name":"chart_id","in":"path","required":true,"schema":{"type":"string","title":"Chart Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Chart Radv Packets Api V1 Radv Charts  Chart Id  Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/clinical-documents/{doc_id}":{"get":{"tags":["clinical-documents"],"summary":"Get Clinical Document","description":"Return decrypted document text + metadata for evidence highlighting.\n\nOrg-scoped via the document's parent chart. Reading PHI is\naudit-logged.","operationId":"get_clinical_document_api_v1_clinical_documents__doc_id__get","parameters":[{"name":"doc_id","in":"path","required":true,"schema":{"type":"string","title":"Doc Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Clinical Document Api V1 Clinical Documents  Doc Id  Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/analytics/dashboard":{"get":{"tags":["analytics"],"summary":"Plan Dashboard","description":"Plan-level metrics for the calling org.\n\nResolution order for the $-valuation rate:\n    1. ``avg_base_payment_dollars`` query parameter (request-time override)\n    2. ``organizations.avg_base_payment_dollars`` (org-level setting)\n    3. $11,000 hardcoded fallback (CMS MA per-member-per-year base)","operationId":"plan_dashboard_api_v1_analytics_dashboard_get","parameters":[{"name":"avg_base_payment_dollars","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Base Payment Dollars"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Plan Dashboard Api V1 Analytics Dashboard Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/members/{member_id}/raf":{"get":{"tags":["members"],"summary":"Member Raf","description":"Sum RAF across the member's recommendations grouped by HCC.\n\nDefaults to accepted+edited (final-decision codes). Pass\n``statuses=accepted,edited,pending`` to include open suggestions.","operationId":"member_raf_api_v1_members__member_id__raf_get","parameters":[{"name":"member_id","in":"path","required":true,"schema":{"type":"string","title":"Member Id"}},{"name":"statuses","in":"query","required":false,"schema":{"type":"string","default":"accepted,edited","title":"Statuses"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Member Raf Api V1 Members  Member Id  Raf Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/members/{member_id}/raf/scenario":{"post":{"tags":["members"],"summary":"Member Raf Scenario","description":"Hypothetical: what would the member-level RAF be if these\npending recommendation IDs were accepted vs rejected?\n\nDoes NOT mutate any recommendation rows — pure read-only.","operationId":"member_raf_scenario_api_v1_members__member_id__raf_scenario_post","parameters":[{"name":"member_id","in":"path","required":true,"schema":{"type":"string","title":"Member Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScenarioRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Member Raf Scenario Api V1 Members  Member Id  Raf Scenario Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/org/settings":{"get":{"tags":["org-settings"],"summary":"Get Settings","operationId":"get_settings_api_v1_org_settings_get","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsResponse"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"patch":{"tags":["org-settings"],"summary":"Patch Settings","operationId":"patch_settings_api_v1_org_settings_patch","parameters":[{"name":"access_token","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsPatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsResponse"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/api/v1/risk-scores/delta":{"post":{"tags":["risk-scores"],"summary":"Raf Delta","description":"Score the baseline and the scenario, then explain the difference.","operationId":"raf_delta_api_v1_risk_scores_delta_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RafDeltaRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Raf Delta Api V1 Risk Scores Delta Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/mcp/info":{"get":{"tags":["mcp"],"summary":"Get Server Info","description":"Get MCP server information.\n\nReturns server metadata including name, version, and capabilities.\n\nIntentionally UNAUTHENTICATED: MCP discovery is conventionally public and this\nreturns only static, non-tenant metadata (no PHI, no tool schemas, no data).\nGating it would break client bootstrap.","operationId":"get_server_info_mcp_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Server Info Mcp Info Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"anyOf":[{"type":"string","title":"Message"},{"properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"additionalProperties":true,"type":"object","required":["code"],"title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice."},{"properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"additionalProperties":true,"type":"object","required":["status"],"title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score."},{"items":{"type":"object"},"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`)."}],"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string."}},"type":"object","required":["detail"],"title":"ErrorResponse"}}}}}}},"/mcp/tools":{"get":{"tags":["mcp"],"summary":"List Tools","description":"List available MCP tools.\n\nReturns tool definitions in MCP format, suitable for client registration.","operationId":"list_tools_mcp_tools_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Tools Mcp Tools Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/mcp/tools/call":{"post":{"tags":["mcp"],"summary":"Call Tool","description":"Execute an MCP tool.\n\nAccepts tool name and arguments, executes the tool, and returns\nthe result in MCP TextContent format.\n\n**Example request:**\n```json\n{\n  \"name\": \"lookup_icd10_code\",\n  \"arguments\": {\"code\": \"E11.22\"}\n}\n```\n\n**Example response:**\n```json\n{\n  \"content\": [\n    {\n      \"type\": \"text\",\n      \"text\": \"{\\\"code\\\": \\\"E11.22\\\", \\\"description\\\": \\\"Type 2 diabetes...\\\", ...}\"\n    }\n  ]\n}\n```","operationId":"call_tool_mcp_tools_call_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Call Tool Mcp Tools Call Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/mcp/schema":{"get":{"tags":["mcp"],"summary":"Get Schema","description":"Get the full MCP schema for this server.\n\nUseful for programmatic client registration and tool discovery.","operationId":"get_schema_mcp_schema_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Schema Mcp Schema Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/tools/openai/schema":{"get":{"tags":["openai-tools"],"summary":"Get Schema","description":"Get tool definitions in OpenAI function calling format.\n\nReturns tools ready to use with OpenAI's chat completions API\nor Responses API.\n\n**Example usage with OpenAI:**\n```python\nimport openai\n\n# Get tools from this endpoint\ntools_response = requests.get(\n    \"https://api.accurecord.io/tools/openai/schema\",\n    headers={\"X-API-Key\": \"your_key\"}\n)\ntools = tools_response.json()[\"tools\"]\n\n# Use with OpenAI\nresponse = openai.chat.completions.create(\n    model=\"gpt-4\",\n    messages=[{\"role\": \"user\", \"content\": \"Code diabetes with CKD\"}],\n    tools=tools,\n    tool_choice=\"auto\"\n)\n```","operationId":"get_schema_tools_openai_schema_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Schema Tools Openai Schema Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/tools/openai/execute":{"post":{"tags":["openai-tools"],"summary":"Execute Openai Tool","description":"Execute a tool call and return result in OpenAI format.\n\nAccepts the tool_call object from an OpenAI response and returns\nthe result ready to append to the messages array.\n\n**Example:**\n```python\n# After getting a tool_call from OpenAI\ntool_call = response.choices[0].message.tool_calls[0]\n\n# Execute it\nresult = requests.post(\n    \"https://api.accurecord.io/tools/openai/execute\",\n    headers={\"X-API-Key\": \"your_key\"},\n    json={\n        \"id\": tool_call.id,\n        \"type\": tool_call.type,\n        \"function\": {\n            \"name\": tool_call.function.name,\n            \"arguments\": tool_call.function.arguments\n        }\n    }\n)\n\n# Append to messages for next turn\nmessages.append(result.json())\n```","operationId":"execute_openai_tool_tools_openai_execute_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAIToolCallRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Execute Openai Tool Tools Openai Execute Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/tools/openai/mcp-config":{"get":{"tags":["openai-tools"],"summary":"Get Mcp Config","description":"Get MCP server configuration for OpenAI Responses API.\n\nReturns configuration suitable for OpenAI's remote MCP support.\n\n**Example:**\n```json\n{\n  \"mcp_servers\": [\n    {\n      \"name\": \"icd10-coding\",\n      \"url\": \"https://api.accurecord.io/mcp\",\n      \"api_key\": \"your_key\"\n    }\n  ]\n}\n```","operationId":"get_mcp_config_tools_openai_mcp_config_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Mcp Config Tools Openai Mcp Config Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/tools/anthropic/schema":{"get":{"tags":["anthropic-tools"],"summary":"Get Schema","description":"Get tool definitions in Anthropic Claude tool_use format.\n\nReturns tools ready to use with Claude's messages API.\n\n**Example usage with Anthropic:**\n```python\nimport anthropic\n\n# Get tools from this endpoint\ntools_response = requests.get(\n    \"https://api.accurecord.io/tools/anthropic/schema\",\n    headers={\"X-API-Key\": \"your_key\"}\n)\ntools = tools_response.json()[\"tools\"]\n\n# Use with Claude\nclient = anthropic.Anthropic()\nresponse = client.messages.create(\n    model=\"claude-sonnet-4-20250514\",\n    max_tokens=1024,\n    tools=tools,\n    messages=[{\"role\": \"user\", \"content\": \"Code diabetes with CKD\"}]\n)\n```","operationId":"get_schema_tools_anthropic_schema_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Schema Tools Anthropic Schema Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/tools/anthropic/execute":{"post":{"tags":["anthropic-tools"],"summary":"Execute Anthropic Tool","description":"Execute a tool_use block and return tool_result.\n\nAccepts the tool_use block from a Claude response and returns\nthe result ready to send back as a tool_result.\n\n**Example:**\n```python\n# After getting a tool_use from Claude\ntool_use = next(\n    block for block in response.content\n    if block.type == \"tool_use\"\n)\n\n# Execute it\nresult = requests.post(\n    \"https://api.accurecord.io/tools/anthropic/execute\",\n    headers={\"X-API-Key\": \"your_key\"},\n    json={\n        \"id\": tool_use.id,\n        \"name\": tool_use.name,\n        \"input\": tool_use.input\n    }\n)\n\n# Send back to Claude as tool_result\nmessages.append({\n    \"role\": \"user\",\n    \"content\": [result.json()]\n})\n```","operationId":"execute_anthropic_tool_tools_anthropic_execute_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnthropicToolUseRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Execute Anthropic Tool Tools Anthropic Execute Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/tools/anthropic/skill":{"get":{"tags":["anthropic-tools"],"summary":"Get Skill Definition","description":"Get skill definition for agent discovery platforms.\n\nReturns SKILL.md-compatible metadata for platforms like agentskills.io.","operationId":"get_skill_definition_tools_anthropic_skill_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Skill Definition Tools Anthropic Skill Get"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit exceeded for this key's tier, or the coding surface is at capacity. Read `X-RateLimit-Reset-Minute` for the backoff rather than retrying immediately — an AI coding call is metered as a billable unit and a retry storm is charged.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"The coding brain cannot serve this request: the LLM circuit breaker is OPEN after repeated upstream failures, or the CPT surface is switched off / its reference data is unbuilt. ⚠ A breaker that opens MID-request does NOT surface here — the pipeline degrades rather than fails and says so in the 200 body's `degradations[]` (kind `llm_circuit_open`). Read that list: a degraded answer is shaped exactly like a healthy one.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}}}}},"/fhir/ehr/launch":{"get":{"tags":["fhir-ehr"],"summary":"Ehr Launch","description":"EHR launch entry point: redirect to the EHR's authorize endpoint (PKCE S256).","operationId":"ehr_launch_fhir_ehr_launch_get","parameters":[{"name":"iss","in":"query","required":true,"schema":{"type":"string","description":"EHR FHIR base URL (issuer)","title":"Iss"},"description":"EHR FHIR base URL (issuer)"},{"name":"launch","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque EHR launch token","title":"Launch"},"description":"Opaque EHR launch token"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/fhir/ehr/callback":{"get":{"tags":["fhir-ehr"],"summary":"Ehr Callback","description":"EHR redirect: exchange code for the EHR token; persist an encrypted ``EHRSession``.","operationId":"ehr_callback_fhir_ehr_callback_get","parameters":[{"name":"code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"}},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"}},{"name":"error","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/fhir/ehr/session/{session_id}/code":{"post":{"tags":["fhir-ehr"],"summary":"Ehr Session Code","description":"Read the launched patient's chart from the EHR, scrub, and run the coder.","operationId":"ehr_session_code_fhir_ehr_session__session_id__code_post","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Ehr Session Code Fhir Ehr Session  Session Id  Code Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/fhir/ehr/session/{session_id}/writeback":{"post":{"tags":["fhir-ehr"],"summary":"Ehr Session Writeback","description":"Write a coded Condition back to the EHR (gated on a Condition write scope).","operationId":"ehr_session_writeback_fhir_ehr_session__session_id__writeback_post","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WritebackRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Ehr Session Writeback Fhir Ehr Session  Session Id  Writeback Post"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/scim/v2/ServiceProviderConfig":{"get":{"tags":["scim"],"summary":"Service Provider Config","operationId":"service_provider_config_scim_v2_ServiceProviderConfig_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScimServiceProviderConfig"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/scim/v2/Users":{"get":{"tags":["scim"],"summary":"List Users","description":"List org members; supports the ``userName eq \"x\"`` filter IdPs use to dedup.","operationId":"list_users_scim_v2_Users_get","parameters":[{"name":"filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filter"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScimListResponse"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"post":{"tags":["scim"],"summary":"Create User","description":"Provision a user into the org (idempotent on email + membership).","operationId":"create_user_scim_v2_Users_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScimUserResource"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}},"/scim/v2/Users/{user_id}":{"get":{"tags":["scim"],"summary":"Get User","operationId":"get_user_scim_v2_Users__user_id__get","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScimUserResource"}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"patch":{"tags":["scim"],"summary":"Patch User","description":"Apply a PatchOp — the IdP deprovisions by setting ``active=false``.","operationId":"patch_user_scim_v2_Users__user_id__patch","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}},"delete":{"tags":["scim"],"summary":"Delete User","description":"Deprovision: remove the org membership (global account is preserved).","operationId":"delete_user_scim_v2_Users__user_id__delete","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Malformed or out-of-bounds request — a batch over 50 codes, a file over the upload limit, an unparseable identifier, or a surface that is switched off in this environment (the `cpt_*_disabled` gates are 400, not 403). ⚠ Not interchangeable with 422: 400 is raised BY the handler, 422 by request validation.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"401":{"description":"Missing, malformed, revoked or expired credential. Send the key as `X-API-Key` or `Authorization: Bearer`. `detail` is a string, except the MFA challenge on `/auth/login`, which is `{code: 'mfa_required', message}`.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"403":{"description":"Authenticated but not permitted: the tier does not include the feature, the role is insufficient, or the free tier is paused. Gate-specific bodies use the `{code, message}` shape (`tier_required`, `insufficient_role`). ⚠ The free-tier pause is the ONE error in the service that does not use `detail` at all — its body is `{error: 'free_tier_paused', message}` at the top level. ⚠ Preconditions the caller CAN satisfy (no org, no BAA, PHI mode off) are 412, not 403 — see below.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"404":{"description":"Resource, code, or org-scoped record not found. Note that a record belonging to ANOTHER organization is also a 404, never a 403 — existence is not disclosed across tenants.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"412":{"description":"A precondition on the calling principal is unmet and the caller can fix it: no organization linked to the key (`org_required`), no signed BAA (`baa_required`), PHI mode not activated (`phi_not_activated`), reviewer mode off (`review_mode_disabled`), or the session was never second-factored (`mfa_required`). All use the `{code, message}` shape.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"422":{"description":"Request body or query failed validation. FastAPI's own failures are a LIST of `{loc, msg, type}`; semantic refusals raised by the service are an object (the risk-adjustment endpoints use `{status, ...}`).","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}},"429":{"description":"Rate limit, quota or concurrency cap exceeded. The tier limiter, the per-key chart-review job cap, the anonymous demo cap and the auth/signup limiters all land here; only the tier limiter sets the `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-RateLimit-Limit-Minute":{"description":"Per-minute request allowance for this key's tier.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"description":"Requests left in the current minute window.","schema":{"type":"integer"}},"X-RateLimit-Reset-Minute":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"description":"Per-day allowance. Absent for tiers with no daily cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"description":"Requests left today. Absent for tiers with no daily cap.","schema":{"type":"integer"}}}},"500":{"description":"Unhandled server error. The body is `{detail: 'Internal server error', request_id: <id>}` and the same id is on the `X-Request-ID` response header.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}},"headers":{"X-Request-ID":{"description":"Correlation id for this request. Quote it in a support ticket — it is the key the server-side log line is written under.","schema":{"type":"string"}}}},"503":{"description":"A dependency this request needed is unavailable — the database, an upstream model provider, or reference data that is present but not READY. Retry is reasonable, except for the risk-adjustment `blocked_pack_not_ready` refusals, which stay 503 until the coefficient pack is actually loaded.","content":{"application/json":{"schema":{"title":"ErrorResponse","type":"object","properties":{"detail":{"title":"ErrorDetail","description":"Polymorphic. Most gates emit a human-readable string; the machine-readable gates emit an object keyed `code` (auth/tier/CPT gates) or `status` (risk-adjustment refusals); FastAPI request validation emits a list. Branch on the JSON type — do not assume a string.","anyOf":[{"type":"string","title":"Message"},{"type":"object","title":"CodedError","description":"Machine-readable gate. `code` is stable and safe to branch on; `message` is human-facing prose and may change without notice.","properties":{"code":{"type":"string","examples":["org_required","baa_required"]},"message":{"type":"string"}},"required":["code"],"additionalProperties":true},{"type":"object","title":"TypedRefusal","description":"Risk-adjustment refusal. `status` names WHY no score was produced and the sibling keys say what would fix it (`missing`, `valid_segments`, `pack_status`). These endpoints refuse rather than return a 0.0 that reads like a real score.","properties":{"status":{"type":"string","examples":["blocked_pack_not_ready","blocked_segment_unknown"]}},"required":["status"],"additionalProperties":true},{"type":"array","title":"ValidationErrors","description":"FastAPI request-validation failures (`loc` / `msg` / `type`).","items":{"type":"object"}}]}},"required":["detail"]}}}}}}}},"components":{"schemas":{"AdmissionOrderInput":{"properties":{"order_evidence_span":{"type":"string","title":"Order Evidence Span"},"order_datetime":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Order Datetime"}},"type":"object","required":["order_evidence_span"],"title":"AdmissionOrderInput","description":"A formal inpatient admission is DERIVED from a documented admission order; it is not\na caller-settable boolean anywhere in A5, so a caller cannot assert an admission the\nchart does not show. A blank evidence span is refused."},"AnthropicToolUseRequest":{"properties":{"id":{"type":"string","title":"Id","description":"Tool use ID from Claude response"},"name":{"type":"string","title":"Name","description":"Tool name"},"input":{"additionalProperties":true,"type":"object","title":"Input","description":"Tool input arguments"}},"type":"object","required":["id","name","input"],"title":"AnthropicToolUseRequest","description":"Request matching Anthropic tool_use block format."},"ArtifactClassificationInput":{"properties":{"artifact_ref":{"type":"string","title":"Artifact Ref"},"facts":{"$ref":"#/components/schemas/DocumentFactsInput"},"stamps":{"items":{"$ref":"#/components/schemas/PolicyStampInput"},"type":"array","title":"Stamps"},"parent_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Ref"}},"type":"object","required":["artifact_ref","facts"],"title":"ArtifactClassificationInput","description":"A3's per-artifact exit record — typed upstream (DI + closed-set adjudication) and\nhanded in here. The pipeline reads ONLY the stamp for the named program namespace; it\nnever invents a document type, and eligibility never transfers between artifacts (a\nstamp minted for another artifact_ref is refused at construction)."},"AuthenticationMethod":{"type":"string","enum":["handwritten","electronic","attestation","signature_log","stamp"],"title":"AuthenticationMethod","description":"HOW a note was authenticated (§A6.4 owner ruling).\n\nFour methods are acceptable; a signature STAMP is rejected UNLESS a documented\ndisability accommodation is present — see :class:`SignatureAttestation`, whose\n``status`` maps a bare (unaccommodated) stamp to ``SIGNATURE_STAMP_REJECTED`` so the\npassing ``SIGNED_AND_DATED`` state is unconstructible from a stamp."},"AuthorRole":{"type":"string","enum":["diagnosing_provider","nurse","therapist","patient","facility_staff","facility_system","unknown"],"title":"AuthorRole"},"AutonomousConfigRequest":{"properties":{"autonomous_threshold":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Autonomous Threshold"},"autonomous_blocking_severity":{"anyOf":[{"type":"string","pattern":"^(error|warning|info)$"},{"type":"null"}],"title":"Autonomous Blocking Severity"}},"type":"object","title":"AutonomousConfigRequest","description":"Update an org's autonomous-mode configuration."},"AzureWebhook":{"properties":{"action":{"type":"string","title":"Action"},"subscriptionId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscriptionid"},"planId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Planid"},"quantity":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Quantity"},"operationId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operationid"}},"type":"object","required":["action"],"title":"AzureWebhook"},"BAAAcceptRequest":{"properties":{"org_slug":{"type":"string","minLength":1,"title":"Org Slug"},"baa_version":{"type":"string","minLength":1,"title":"Baa Version","description":"Version from /legal/baa/document"},"capacity":{"type":"string","title":"Capacity","description":"'covered_entity', or 'business_associate' for a client that is itself a business associate or subcontractor of a covered entity (a different BAA text)."},"text_sha256":{"type":"string","maxLength":64,"minLength":64,"title":"Text Sha256","description":"SHA-256 of the exact text shown, as returned by /legal/baa/document."},"authority_affirmed":{"type":"boolean","title":"Authority Affirmed","description":"The signer affirms, separately from accepting the text, that they are authorized to bind the organization named below to this BAA."},"signer_name":{"type":"string","maxLength":200,"minLength":1,"title":"Signer Name"},"signer_title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Signer Title"},"legal_entity_name":{"type":"string","maxLength":300,"minLength":1,"title":"Legal Entity Name","description":"The legal entity the BAA binds."},"effective_scope":{"items":{"type":"string"},"type":"array","title":"Effective Scope","description":"Services the BAA covers. Clickwrap covers the Coding API only."},"upstream_rights_contact":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Upstream Rights Contact","description":"Required for a business associate: how individual-rights requests reach the Upstream Covered Entity."}},"type":"object","required":["org_slug","baa_version","capacity","text_sha256","authority_affirmed","signer_name","legal_entity_name"],"title":"BAAAcceptRequest"},"BatchCodesRequest":{"properties":{"codes":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Codes","description":"List of ICD-10-CM codes to look up"},"year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year","description":"Fiscal year version"},"include_inherited":{"type":"boolean","title":"Include Inherited","description":"Include inherited notes","default":true}},"type":"object","required":["codes"],"title":"BatchCodesRequest","description":"Request body for bulk code lookup."},"BatchHCCRequest":{"properties":{"codes":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Codes","description":"List of ICD-10-CM codes"},"year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year","description":"Fiscal year version"},"include_weights":{"type":"boolean","title":"Include Weights","description":"Include RAF weights for each category","default":false},"payment_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Payment Year","description":"Payment year for weight lookup"}},"type":"object","required":["codes"],"title":"BatchHCCRequest","description":"Request body for bulk HCC lookup."},"BatchHCCSuppressRequest":{"properties":{"codes":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Codes","description":"List of ICD-10-CM codes"},"year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year","description":"Fiscal year version"},"model_type":{"type":"string","title":"Model Type","description":"HCC model: CMS-HCC, RxHCC, HHS-HCC, ESRD","default":"CMS-HCC"},"model_version":{"type":"string","title":"Model Version","description":"Model version: V24, V28, V06, etc.","default":"V28"},"payment_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Payment Year","description":"Payment year for weights"},"segment":{"type":"string","title":"Segment","description":"Beneficiary segment for weight lookup","default":"community_nondual_aged"}},"type":"object","required":["codes"],"title":"BatchHCCSuppressRequest","description":"Request body for HCC suppression analysis."},"BenefitType":{"type":"string","enum":["part_c","part_d_mapd","part_d_pdp","commercial_qhp"],"title":"BenefitType"},"Body_aws_register_api_v1_marketplace_aws_register_post":{"properties":{"x-amzn-marketplace-token":{"type":"string","title":"X-Amzn-Marketplace-Token"}},"type":"object","required":["x-amzn-marketplace-token"],"title":"Body_aws_register_api_v1_marketplace_aws_register_post"},"Body_upload_chart_api_v1_chart_review_upload_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"},"year":{"type":"integer","title":"Year"},"include_hcc":{"type":"boolean","title":"Include Hcc","default":false},"use_batch":{"type":"boolean","title":"Use Batch","default":false}},"type":"object","required":["file"],"title":"Body_upload_chart_api_v1_chart_review_upload_post"},"BrandingView":{"properties":{"product_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Name"},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url"},"favicon_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Favicon Url"},"primary_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Color"},"secondary_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Secondary Color"},"support_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Support Email"},"terms_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Terms Url"},"docs_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Docs Url"}},"additionalProperties":true,"type":"object","title":"BrandingView"},"BreachReportRequest":{"properties":{"org_slug":{"type":"string","title":"Org Slug","description":"Slug of the affected organization"},"breach_type":{"type":"string","title":"Breach Type","description":"e.g. unauthorized_access, lost_device, misdirected_phi"},"description":{"type":"string","title":"Description","description":"What happened (stored encrypted)"},"discovered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Discovered At"},"individuals_affected":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Individuals Affected"}},"type":"object","required":["org_slug","breach_type","description"],"title":"BreachReportRequest"},"CPTAIMetadata":{"properties":{"algorithm_name":{"type":"string","minLength":1,"title":"Algorithm Name"},"algorithm_version":{"type":"string","minLength":1,"title":"Algorithm Version"},"fda_clearance":{"type":"string","minLength":1,"title":"Fda Clearance","description":"510(k) clearance number"}},"type":"object","required":["algorithm_name","algorithm_version","fda_clearance"],"title":"CPTAIMetadata"},"CalculationMode":{"type":"string","enum":["internal_projection","submission_reconciled_projection","cms_reported_reconciliation"],"title":"CalculationMode","description":"D3's three modes — and the ``calculation_mode`` every numeric carries.\n\n``internal_projection`` is what the engine can compute from its own chart-derived,\nC8-eligible evidence. Only ``cms_reported_reconciliation`` may ever be labeled the\nofficial factor (enforced by :class:`CmsReportedFactor`)."},"CareSetting":{"type":"string","enum":["inpatient_acute","observation","emergency_department","hospital_outpatient","office","skilled_nursing_facility","standalone_diagnostic"],"title":"CareSetting","description":"The A5 setting vocabulary (step map: IP / OP / office / ED / obs / SNF).\n\nTelehealth is deliberately NOT a member — §A4.7 rules it a MODALITY. An encounter\nconducted by video is ``OFFICE`` + ``Modality.TELEHEALTH_SYNCHRONOUS_AUDIO_VIDEO``."},"ChangePasswordRequest":{"properties":{"current_password":{"type":"string","title":"Current Password"},"new_password":{"type":"string","title":"New Password"}},"type":"object","required":["current_password","new_password"],"title":"ChangePasswordRequest"},"CheckoutRequest":{"properties":{"plan":{"type":"string","const":"pro","title":"Plan","default":"pro"},"success_url":{"type":"string","title":"Success Url","default":"https://accurecord.io/billing?status=success"},"cancel_url":{"type":"string","title":"Cancel Url","default":"https://accurecord.io/billing?status=cancel"}},"additionalProperties":false,"type":"object","title":"CheckoutRequest"},"ClinicalRole":{"type":"string","enum":["assessment","test_interpretation","procedure","treatment_administration","patient_report","not_documented"],"title":"ClinicalRole"},"CodeEvidenceItem":{"properties":{"code":{"type":"string","title":"Code"},"spans":{"items":{"$ref":"#/components/schemas/EvidenceSpan"},"type":"array","title":"Spans"}},"type":"object","required":["code","spans"],"title":"CodeEvidenceItem","description":"One code and the chart evidence that grounds it."},"CodeRequest":{"properties":{"condition":{"type":"string","maxLength":2000,"minLength":1,"title":"Condition","description":"Natural language condition description","examples":["DM2 with CKD stage 3","acute bronchitis","hip fracture right"]},"year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year","description":"ICD-10-CM fiscal year"},"include_hcc":{"type":"boolean","title":"Include Hcc","description":"Include HCC risk adjustment information","default":false},"prior_codes":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":200},{"type":"null"}],"title":"Prior Codes","description":"Codes already assigned earlier in this encounter. Triggers cross-condition excludes1 detection."},"encounter_metadata":{"anyOf":[{"$ref":"#/components/schemas/EncounterMetadata"},{"type":"null"}],"description":"Optional age/sex/principal-code context for denial-prevention rules."},"code_uncertain_diagnoses":{"type":"boolean","title":"Code Uncertain Diagnoses","description":"Code uncertain/probable/rule-out/differential diagnoses as if established (inpatient & discharge-summary coding, ICD-10-CM Guideline II.H). Each such code is labelled `coded_as_uncertain` in the per-concept output and flagged in warnings. Default false keeps the outpatient rule (Guideline IV.H): uncertain dx are not coded.","default":false},"meat_profile":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Meat Profile","description":"Name of the MEAT profile to use for evidence extraction (e.g. 'radv_strict' or 'ma_lite'). Falls back to the org's default profile if unset, or omits MEAT entirely if no profile is configured."},"coding_policy":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Coding Policy","description":"Name of the per-project coding-policy profile (Layer 2 rules: code/don't-code by chart section, chronic recapture, etc.). Falls back to the org's default policy if unset; if neither exists, coding behavior is unchanged."},"hcc_model_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hcc Model Version","description":"HCC model version for RAF computation: 'V28' (CY2026 default) or 'V24' (legacy). Falls back to the org's preferred_hcc_model_version, then to V28."},"hcc_segment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hcc Segment","description":"Beneficiary segment for RAF lookup, e.g. 'community_nondual_aged' (default), 'institutional', 'community_full_dual_aged'."},"payer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payer","description":"Payer slug ('uhc', 'humana', 'aetna', 'anthem', 'kaiser', etc.). Surfaces payer-specific denial rules in the response's verification.findings under detail.payer."},"chart_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chart Id","description":"Optional chart_review_jobs.id this coding belongs to. Passing it (or member_id below) opts the request into reviewer mode: each verified code is persisted as a Recommendation row reviewable via /api/v1/reviewer/* endpoints."},"member_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member Id","description":"Optional members.id this coding belongs to. Like chart_id, passing it opts the request into reviewer mode."},"previously_submitted_codes":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":200},{"type":"null"}],"title":"Previously Submitted Codes","description":"Codes ALREADY SENT TO THE PAYER for this member, to be reviewed against what this chart documents. Returns a `support_review` block per code. ⚠ This is NOT `prior_codes`: that means codes assigned earlier in THIS encounter and exists so the Excludes1 engine can see them. This asks the opposite question — does the documentation still support a code someone already submitted? Requires the support_review_enabled deployment flag (explicit 400 when off)."},"include_hcc_decisions":{"type":"boolean","title":"Include Hcc Decisions","description":"Include `hcc_decisions[]` — one decision object per candidate diagnosis, saying which codes it produced, which chart spans licensed them, which findings applied and what it contributed to RAF. Modelled on include_hcc: opt-in, and never changes the codes. Requires an HCC-enabled key (403 otherwise) and the hcc_lane_enabled deployment flag (explicit 400 when off, never a silent omission).","default":false}},"type":"object","required":["condition"],"title":"CodeRequest","description":"Request body for AI coding."},"CommissionEntry":{"properties":{"customer_org_id":{"type":"string","title":"Customer Org Id"},"units":{"type":"integer","title":"Units"},"gross_amount_cents":{"type":"integer","title":"Gross Amount Cents"},"commission_model":{"type":"string","title":"Commission Model"},"commission_amount_cents":{"type":"integer","title":"Commission Amount Cents"},"currency":{"type":"string","title":"Currency"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"additionalProperties":true,"type":"object","required":["customer_org_id","units","gross_amount_cents","commission_model","commission_amount_cents","currency","created_at"],"title":"CommissionEntry"},"CommissionsResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"commissions":{"items":{"$ref":"#/components/schemas/CommissionEntry"},"type":"array","title":"Commissions"},"total_commission_cents":{"type":"integer","title":"Total Commission Cents"}},"additionalProperties":true,"type":"object","required":["success","commissions","total_commission_cents"],"title":"CommissionsResponse"},"CptClaimLineRequest":{"properties":{"code":{"type":"string","maxLength":7,"minLength":2,"title":"Code","description":"CPT or HCPCS code"},"modifiers":{"items":{"type":"string"},"type":"array","maxItems":8,"title":"Modifiers","description":"Modifiers on THIS line. Per-line, not per-claim: NCCI asks whether the bypass modifier is on the denied (column 2) line specifically."},"units":{"type":"integer","maximum":9999.0,"minimum":1.0,"title":"Units","description":"Units billed on this line","default":1},"dx_pointers":{"items":{"type":"string"},"type":"array","maxItems":4,"title":"Dx Pointers","description":"Box 24E: letters (A-L) into the claim's `diagnoses`, primary first."},"dos":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Dos","description":"Date of service. Without it the billability and date-of-service edits cannot run, and the response says so rather than reporting the claim clean."}},"type":"object","required":["code"],"title":"CptClaimLineRequest"},"CptCodeRequest":{"properties":{"chart_text":{"type":"string","maxLength":200000,"minLength":1,"title":"Chart Text","description":"Operative note or encounter documentation. ⚠ PHI."},"practice_setting":{"type":"string","title":"Practice Setting","default":"practitioner"},"dos":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Dos","description":"Date of service"},"prior_procedures":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":50,"title":"Prior Procedures"},"patient_age":{"anyOf":[{"type":"integer","maximum":130.0,"minimum":0.0},{"type":"null"}],"title":"Patient Age"},"patient_sex":{"anyOf":[{"type":"string","maxLength":1},{"type":"null"}],"title":"Patient Sex"},"em_family":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Em Family","description":"Level the visit's E/M too, e.g. 'office_established'. ⚠ Required from you rather than inferred — new-vs-established and office-vs-hospital are facts about the encounter a note frequently does not state. Adds one LLM call."},"version":{"anyOf":[{"type":"integer","maximum":2100.0,"minimum":2000.0},{"type":"null"}],"title":"Version"},"payer_type":{"anyOf":[{"type":"string","enum":["medicare_ffs","medicare_advantage","medicaid","commercial"]},{"type":"null"}],"title":"Payer Type","description":"Who pays. Optional. Known: Medicare's dispositions are enforced for medicare_ffs (PFS N/B and HCPCS coverage I/M/S become blocking errors); for medicare_advantage Medicare's coding and coverage are stated as warnings, because the plan's own billing instructions decide; for medicaid/commercial a Medicare status is stated but never generalised. Absent: the payer is unresolved: every Medicare disposition is a warning that says so, and a line whose code depends on the payer is flagged, not billed as sent."},"payer_state":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$"},{"type":"null"}],"title":"Payer State","description":"Two-letter state of the Medicaid programme. Only with payer_type=medicaid."},"diagnoses":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":12},{"type":"null"}],"title":"Diagnoses","description":"The claim's Box 21 diagnoses, ICD-10-CM, lettered A-L in this order. Optional. Codes are checked as billable for the fiscal year of the date of service. Pointers are CHART-LINKED ONLY: a line points at a diagnosis only where the chart explicitly ties that service to it (quoted verbatim), otherwise the line carries the review item 'dx pointer not documented' — never a default."}},"type":"object","required":["chart_text"],"title":"CptCodeRequest"},"CptValidateRequest":{"properties":{"lines":{"items":{"$ref":"#/components/schemas/CptClaimLineRequest"},"type":"array","maxItems":200,"minItems":1,"title":"Lines"},"practice_setting":{"type":"string","title":"Practice Setting","description":"'practitioner', 'hospital' or 'dme_supplier'. ⚠ These are SEPARATE NCCI rulebooks, not a refinement of one another — a pair may be bundled in one and absent in the other. The default is practitioner; a facility biller must set it. 'dme_supplier' applies CMS's DME MUE edition; no NCCI PTP edition exists for it and the response says so.","default":"practitioner"},"prior_procedures":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":50,"title":"Prior Procedures","description":"Procedures performed on EARLIER claims, as {code, date}, for post-operative window checks. Omitting them does not mean there was no surgery — the global-period engine reports that it could not run."},"patient_age":{"anyOf":[{"type":"integer","maximum":130.0,"minimum":0.0},{"type":"null"}],"title":"Patient Age"},"patient_sex":{"anyOf":[{"type":"string","maxLength":1},{"type":"null"}],"title":"Patient Sex"},"version":{"anyOf":[{"type":"integer","maximum":2100.0,"minimum":2000.0},{"type":"null"}],"title":"Version","description":"CPT CALENDAR year (not the ICD fiscal year). Defaults to the loaded set."},"payer_type":{"anyOf":[{"type":"string","enum":["medicare_ffs","medicare_advantage","medicaid","commercial"]},{"type":"null"}],"title":"Payer Type","description":"Who pays. Optional. Known: Medicare's dispositions are enforced for medicare_ffs (PFS N/B and HCPCS coverage I/M/S become blocking errors); for medicare_advantage Medicare's coding and coverage are stated as warnings, because the plan's own billing instructions decide; for medicaid/commercial a Medicare status is stated but never generalised. Absent: the payer is unresolved: every Medicare disposition is a warning that says so, and a line whose code depends on the payer is flagged, not billed as sent."},"payer_state":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$"},{"type":"null"}],"title":"Payer State","description":"Two-letter state of the Medicaid programme. Only with payer_type=medicaid."},"diagnoses":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":12},{"type":"null"}],"title":"Diagnoses","description":"The claim's Box 21 diagnoses, ICD-10-CM, lettered A-L in this order. Optional. Codes are checked as billable for the fiscal year of the date of service. Pointers are CHART-LINKED ONLY: a line points at a diagnosis only where the chart explicitly ties that service to it (quoted verbatim), otherwise the line carries the review item 'dx pointer not documented' — never a default."}},"type":"object","required":["lines"],"title":"CptValidateRequest"},"CreateKeyRequest":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"}},"type":"object","title":"CreateKeyRequest"},"CreateMemberRequest":{"properties":{"member_external_id":{"type":"string","maxLength":200,"minLength":1,"title":"Member External Id"},"dob":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dob","description":"ISO-8601 date string"},"sex":{"anyOf":[{"type":"string","pattern":"^(M|F|O|U)$"},{"type":"null"}],"title":"Sex"},"plan_id":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Plan Id"},"enrollment_segment":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Enrollment Segment"},"notes":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Notes"}},"type":"object","required":["member_external_id"],"title":"CreateMemberRequest"},"CreateOrgRequest":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"slug":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Slug"}},"type":"object","required":["name"],"title":"CreateOrgRequest"},"CreatePMPMContractRequest":{"properties":{"members_covered":{"type":"integer","minimum":0.0,"title":"Members Covered"},"pmpm_rate_cents":{"type":"integer","minimum":1.0,"title":"Pmpm Rate Cents"},"currency":{"type":"string","title":"Currency","default":"usd"},"billing_cycle":{"type":"string","pattern":"^(monthly|quarterly|annual)$","title":"Billing Cycle","default":"monthly"},"effective_from":{"type":"string","title":"Effective From"},"effective_to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effective To"},"contract_doc_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contract Doc Url"}},"type":"object","required":["members_covered","pmpm_rate_cents","effective_from"],"title":"CreatePMPMContractRequest"},"CreatePolicyRequest":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z0-9_]+$","title":"Name"},"policy":{"additionalProperties":true,"type":"object","title":"Policy"},"is_default":{"type":"boolean","title":"Is Default","default":false}},"type":"object","required":["name"],"title":"CreatePolicyRequest"},"CreateProfileRequest":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z0-9_]+$","title":"Name"},"criteria_required":{"items":{"type":"string"},"type":"array","title":"Criteria Required"},"evidence_format":{"type":"string","title":"Evidence Format","default":"verbatim"},"evidence_granularity":{"type":"string","title":"Evidence Granularity","default":"sentence"},"confidence_reporting":{"type":"string","title":"Confidence Reporting","default":"numeric"},"custom_extensions":{"anyOf":[{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array"},{"type":"null"}],"title":"Custom Extensions"},"is_default":{"type":"boolean","title":"Is Default","default":false}},"type":"object","required":["name"],"title":"CreateProfileRequest"},"CreateSessionRequest":{"properties":{"metadata":{"anyOf":[{"$ref":"#/components/schemas/SessionMetadata"},{"type":"null"}]}},"type":"object","title":"CreateSessionRequest"},"CreateWebhookRequest":{"properties":{"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"events":{"items":{"type":"string"},"type":"array","title":"Events"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["url"],"title":"CreateWebhookRequest"},"CustomerListResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"customers":{"items":{"$ref":"#/components/schemas/LinkView"},"type":"array","title":"Customers"}},"additionalProperties":true,"type":"object","required":["success","customers"],"title":"CustomerListResponse"},"CustomerSummary":{"properties":{"org_id":{"type":"string","title":"Org Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"tier":{"type":"string","title":"Tier"}},"additionalProperties":true,"type":"object","required":["org_id","slug","name","tier"],"title":"CustomerSummary"},"DemoCodeRequest":{"properties":{"case_id":{"type":"string","maxLength":64,"minLength":1,"title":"Case Id","description":"Id of a case from GET /api/v1/demo/cases, e.g. 'DEMO-2026-001'.","examples":["DEMO-2026-001"]},"include_hcc":{"type":"boolean","title":"Include Hcc","description":"Include HCC/RAF risk-adjustment output. Requires an HCC-enabled (paid) key.","default":false}},"additionalProperties":false,"type":"object","required":["case_id"],"title":"DemoCodeRequest","description":"⚠ Deliberately carries NO free-text field — see this module's docstring.\n\n`extra=\"forbid\"` rather than Pydantic's default `ignore`, deliberately. Ignoring an\nunexpected `condition` is safe for us — the engine never sees it — but it answers 200\nwith a coded result for a DIFFERENT chart, so someone who pasted a real patient note\nwould reasonably conclude it had been processed. On a boundary whose whole purpose is\n\"no real patient data here\", the caller has to be told no, not quietly handed a\nplausible answer. A 422 naming the rejected field is that refusal."},"Demographics":{"properties":{"dob":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Dob","description":"Date of birth. No default — see the module docs."},"sex":{"anyOf":[{"type":"integer","maximum":2.0,"minimum":1.0},{"type":"null"}],"title":"Sex","description":"1 = male, 2 = female (CMS coding)"},"orec":{"anyOf":[{"type":"integer","maximum":3.0,"minimum":0.0},{"type":"null"}],"title":"Orec","description":"Original reason for entitlement"},"ltimcaid":{"anyOf":[{"type":"integer","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Ltimcaid","description":"Medicaid dummy, long-term inst."},"nemcaid":{"anyOf":[{"type":"integer","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Nemcaid","description":"Medicaid dummy, new enrollee"},"age_last":{"anyOf":[{"type":"integer","maximum":125.0,"minimum":0.0},{"type":"null"}],"title":"Age Last","description":"HHS-HCC: age on the last day of enrolment in the benefit year. Selects the Adult / Child / Infant model. Never derived from dob."},"metal":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Metal","description":"HHS-HCC: plan metal level (P/G/S/B/C, or the full name). Selects which of the five scored columns is the member's own score; all five are returned regardless."},"csr_indicator":{"anyOf":[{"type":"integer","maximum":11.0,"minimum":1.0},{"type":"null"}],"title":"Csr Indicator","description":"HHS-HCC: person-level cost-sharing-reduction indicator. Absent means no CSR-adjusted score is reported — it is never defaulted to 1."},"enrolduration":{"anyOf":[{"type":"integer","maximum":12.0,"minimum":1.0},{"type":"null"}],"title":"Enrolduration","description":"HHS-HCC adult model: months enrolled in the benefit year."}},"type":"object","title":"Demographics","description":"⚠ EVERY FIELD IS OPTIONAL HERE AND REQUIRED BY THE SCORER, NOT BY THIS MODEL.\n\nWhich ones a request must carry is a property of the model family, so it is read from\n``scorer.required_demographics()`` rather than fixed here. The five Medicare fields used\nto be hardcoded, and a request for a family that has no OREC — every HHS-HCC request —\nwas rejected for missing one before ``get_scorer`` was ever consulted.\n\nWhat is NOT negotiable is that nothing is defaulted. The RA pipeline used to substitute\n``dob=1950-01-01, sex=2, orec=0``, which scored a member with no date of birth as a\n76-year-old female and reported success."},"DiagnosisIn":{"properties":{"code":{"type":"string","maxLength":10,"minLength":3,"title":"Code","description":"ICD-10-CM, dots optional"},"poa":{"anyOf":[{"type":"string","maxLength":1},{"type":"null"}],"title":"Poa","description":"Present-on-admission: Y, N, U, W, or 1 (exempt). REQUIRED — a missing POA is refused with drg_poa_missing, never defaulted."}},"type":"object","required":["code"],"title":"DiagnosisIn"},"DocumentEvidenceInput":{"properties":{"content_signature_mime":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Signature Mime","description":"The content-SNIFFED MIME. A filename extension is never authoritative here; acceptance requires a verified signature, and null is not a pass."},"supported_mime_types":{"items":{"type":"string"},"type":"array","title":"Supported Mime Types"},"malware_scan_clean":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Malware Scan Clean","description":"null = the scan did not run. It fails closed, never open."},"password_protected":{"type":"boolean","title":"Password Protected"},"corrupt":{"type":"boolean","title":"Corrupt"},"limits":{"$ref":"#/components/schemas/IngestLimitsInput"},"observed":{"$ref":"#/components/schemas/ObservedUploadInput"},"active_content_disabled":{"type":"boolean","title":"Active Content Disabled"},"external_references_disabled":{"type":"boolean","title":"External References Disabled"},"spreadsheet_formulas_neutralized":{"type":"boolean","title":"Spreadsheet Formulas Neutralized"},"provider_authorized_for_tenant":{"type":"boolean","title":"Provider Authorized For Tenant"},"artifact_classification":{"anyOf":[{"$ref":"#/components/schemas/ArtifactClassificationInput"},{"type":"null"}]},"program_namespace":{"anyOf":[{"$ref":"#/components/schemas/ProgramNamespace"},{"type":"null"}],"description":"Which A3 namespace's stamp to read. A3's namespace vocabulary is distinct from program_ids, so it is named explicitly — never a guessed mapping."}},"type":"object","required":["content_signature_mime","supported_mime_types","malware_scan_clean","password_protected","corrupt","limits","observed","active_content_disabled","external_references_disabled","spreadsheet_formulas_neutralized","provider_authorized_for_tenant"],"title":"DocumentEvidenceInput","description":"A1 (document integrity) + A3 (document typing) inputs.\n\nSupplying this runs the document front-door BEFORE anything else: A1.1 security triage\nfails CLOSED — any non-accepted disposition is a terminal block — and A3's stamp for\n``program_namespace`` becomes the A7 source role, so the role is DOCUMENTED rather than\nasserted at the gate. Omit it and the pipeline behaves as it always has: no document\ngate, and A7 uses the gate evidence's own ``source_role``."},"DocumentFactsInput":{"properties":{"document_family":{"$ref":"#/components/schemas/DocumentFamily"},"document_subtype":{"$ref":"#/components/schemas/DocumentSubtype"},"clinical_role":{"$ref":"#/components/schemas/ClinicalRole"},"author_role":{"$ref":"#/components/schemas/AuthorRole"},"origin":{"$ref":"#/components/schemas/DocumentOrigin"},"lifecycle":{"$ref":"#/components/schemas/DocumentLifecycle"},"structure":{"$ref":"#/components/schemas/DocumentStructure"},"encounter_linkage":{"$ref":"#/components/schemas/EncounterLinkage"},"evidence_span_refs":{"items":{"type":"string"},"type":"array","title":"Evidence Span Refs"}},"type":"object","required":["document_family","document_subtype","clinical_role","author_role","origin","lifecycle","structure","encounter_linkage"],"title":"DocumentFactsInput","description":"A3 §1 — the eight independent factual dimensions the artifact was typed on. There is\ndeliberately no program/HCC input here: facts never bend to a program."},"DocumentFamily":{"type":"string","enum":["encounter_assessment","procedure_treatment","diagnostic_report","clinical_support","administrative_clinical_longitudinal","nonclinical"],"title":"DocumentFamily","description":"The SIX families. Procedure/treatment is deliberately NOT a kind of encounter\nnote, and family alone NEVER determines eligibility."},"DocumentLifecycle":{"type":"string","enum":["draft","final","signed","amended","corrected","retracted","unknown"],"title":"DocumentLifecycle"},"DocumentOrigin":{"type":"string","enum":["original_documentation","imported","copied_forward","claim_prepopulated","patient_generated","unknown"],"title":"DocumentOrigin"},"DocumentRegion":{"properties":{"page":{"type":"integer","title":"Page"},"polygon":{"items":{"type":"number"},"type":"array","title":"Polygon"}},"type":"object","required":["page","polygon"],"title":"DocumentRegion","description":"Where a piece of evidence sits on the page, for highlighting on the original chart.\n\nPopulated only when the OCR provider emitted geometry (Azure DI). ``polygon`` is the word\nbounding box in DI page units: [x1,y1,x2,y2,x3,y3,x4,y4]."},"DocumentStructure":{"type":"string","enum":["standalone","parent","child_artifact","unresolved_composite"],"title":"DocumentStructure"},"DocumentSubtype":{"type":"string","enum":["emergency_department_note","history_and_physical","discharge_summary","office_progress_note","consult_note","telehealth_encounter_note","provider_awv_note","home_physician_visit_note","snf_provider_encounter_note","behavioral_health_note","dialysis_physician_rounding_note","physician_encounter_during_hospice","supervising_provider_infusion_assessment","provider_completed_hra_assessment","operative_report","procedure_note","chemotherapy_infusion_administration","dialysis_treatment_record","radiation_treatment_record","anesthesia_intraoperative_record","pre_anesthesia_assessment","wound_care_procedure","device_placement_or_interrogation","pathology","radiology","clinical_laboratory","cardiology_diagnostic_interpretation","pulmonary_testing","sleep_study","neurodiagnostic","genetic_molecular","device_generated_report","nursing_note","medication_administration_record","therapy_note_pt_ot_st","dialysis_run_sheet","infusion_flowsheet","ems_record","immunization_record","dme_record","telephonic_care_management","snf_nursing_or_mds_record","home_health_agency_note_or_oasis","hospice_facility_documentation","problem_list","medication_list","allergy_list","referral_or_order","superbill","care_plan","questionnaire","patient_completed_hra","correspondence","chart_review_record","fax_cover_sheet","blank_page","explanation_of_benefits","billing_document","consent_form"],"title":"DocumentSubtype","description":"Named subtypes from §1/§3/§7. Each belongs to exactly one family."},"DomainListResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"domains":{"items":{"$ref":"#/components/schemas/DomainView"},"type":"array","title":"Domains"}},"additionalProperties":true,"type":"object","required":["success","domains"],"title":"DomainListResponse"},"DomainView":{"properties":{"id":{"type":"string","title":"Id"},"hostname":{"type":"string","title":"Hostname"},"verified":{"type":"boolean","title":"Verified"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"additionalProperties":true,"type":"object","required":["id","hostname","verified","created_at"],"title":"DomainView"},"DrgGroupRequest":{"properties":{"encounter":{"$ref":"#/components/schemas/EncounterIn"},"principal_dx":{"$ref":"#/components/schemas/DiagnosisIn"},"secondary_dx":{"items":{"$ref":"#/components/schemas/DiagnosisIn"},"type":"array","maxItems":24,"title":"Secondary Dx"},"procedures":{"items":{"type":"string"},"type":"array","maxItems":25,"title":"Procedures"},"admit_dx":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Admit Dx"}},"type":"object","required":["encounter","principal_dx"],"title":"DrgGroupRequest"},"EditRequest":{"properties":{"final_icd10":{"type":"string","maxLength":10,"minLength":1,"title":"Final Icd10"},"note":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Note"}},"type":"object","required":["final_icd10"],"title":"EditRequest"},"EmLevelRequest":{"properties":{"family":{"type":"string","title":"Family","description":"E/M family key, e.g. 'office_established'. ⚠ Required rather than inferred: whether a patient is new or established, and whether the setting is office or hospital, are facts about the encounter that a note frequently does not state and that this service cannot know. Guessing it would change the code."},"chart_text":{"anyOf":[{"type":"string","maxLength":100000},{"type":"null"}],"title":"Chart Text","description":"Visit note. ⚠ PHI — requires an executed BAA and PHI activation."},"observations":{"anyOf":[{"$ref":"#/components/schemas/EmObservationsRequest"},{"type":"null"}],"description":"Pre-extracted observations. Supply these OR chart_text, not neither."}},"type":"object","required":["family"],"title":"EmLevelRequest"},"EmObservationsRequest":{"properties":{"problems":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":50,"title":"Problems"},"data":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":50,"title":"Data"},"risk":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":50,"title":"Risk"},"total_time_minutes":{"anyOf":[{"type":"integer","maximum":1440.0,"minimum":0.0},{"type":"null"}],"title":"Total Time Minutes"},"total_time_evidence":{"items":{"type":"string"},"type":"array","maxItems":10,"title":"Total Time Evidence"}},"type":"object","title":"EmObservationsRequest","description":"Pre-extracted observations, for callers who did their own reading.\n\n⚠ Supplying these SKIPS the LLM entirely, which is the point: a caller with a structured\nEHR feed, or one replaying a stored extraction, gets a byte-identical worksheet with no\nmodel call and no PHI leaving the request."},"EncounterGateEvidenceInput":{"properties":{"care_setting":{"$ref":"#/components/schemas/CareSetting"},"source_role":{"$ref":"#/components/schemas/SourceRole","description":"The caller's asserted A3 role. A document_evidence classification, when supplied, overrides it — a documented role beats an asserted one."},"provider_candidates":{"items":{"$ref":"#/components/schemas/ProviderCandidateInput"},"type":"array","title":"Provider Candidates"},"provider_path":{"$ref":"#/components/schemas/ProviderPath"},"accountable_roles":{"items":{"$ref":"#/components/schemas/ProviderRole"},"type":"array","title":"Accountable Roles"},"provider_rule_version":{"type":"string","title":"Provider Rule Version"},"provider_effective_from":{"type":"string","format":"date","title":"Provider Effective From"},"modality_rule":{"$ref":"#/components/schemas/ProgramModalityRuleInput"},"program":{"type":"string","title":"Program","description":"A7 is stamped per program — name the one."},"admission_order":{"anyOf":[{"$ref":"#/components/schemas/AdmissionOrderInput"},{"type":"null"}]},"professional_service":{"type":"boolean","title":"Professional Service","default":false},"payment_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Payment Year"},"provider_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Provider Effective To"},"project_pack_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Pack Id"},"project_acceptable_provider_types":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProviderType"},"type":"array"},{"type":"null"}],"title":"Project Acceptable Provider Types","description":"Project narrowing. A project may narrow, never widen."},"project_accountable_roles":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProviderRole"},"type":"array"},{"type":"null"}],"title":"Project Accountable Roles"},"project_acceptable_modalities":{"anyOf":[{"items":{"$ref":"#/components/schemas/Modality"},"type":"array"},{"type":"null"}],"title":"Project Acceptable Modalities"}},"type":"object","required":["care_setting","source_role","provider_candidates","provider_path","accountable_roles","provider_rule_version","provider_effective_from","modality_rule","program"],"title":"EncounterGateEvidenceInput","description":"A5/A6/A7 encounter-gate inputs — where RA validity actually lives.\n\nSupplying this runs the real gate (A5 typing → A6 provider binding against the CMS\nlist → A5 modality-eligibility → the A7 stamp) and ROUTES on the stamp: ``unusable``\nand ``blocked_remediable`` are terminal blocks and are never coded; ``evidence_only``\nis coded but no diagnosis enters the submission lane; only ``eligible_for_submission``\nproceeds normally. Omit it and no encounter-level gate runs at all — which is what\nevery request to this endpoint did before this field existed."},"EncounterIn":{"properties":{"admission_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Admission Date"},"discharge_date":{"type":"string","format":"date","title":"Discharge Date","description":"Selects the PCS edition and the grouper version (Oct–Mar / Apr–Sep)."},"age_years":{"anyOf":[{"type":"integer","maximum":124.0,"minimum":0.0},{"type":"null"}],"title":"Age Years"},"sex":{"anyOf":[{"type":"string","maxLength":1},{"type":"null"}],"title":"Sex","description":"M, F or U"},"discharge_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Discharge Status","description":"UB-04 patient discharge status, e.g. 1 home, 20 expired."},"poa_exempt_hospital":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Poa Exempt Hospital","description":"Whether the hospital is exempt from POA reporting."},"age_days_admit":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Age Days Admit"},"age_days_discharge":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Age Days Discharge"}},"type":"object","required":["discharge_date"],"title":"EncounterIn"},"EncounterLinkage":{"type":"string","enum":["linked","provisionally_linked","unlinked","unknown"],"title":"EncounterLinkage"},"EncounterMetadata":{"properties":{"principal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Principal Code"},"patient_age":{"anyOf":[{"type":"integer","maximum":130.0,"minimum":0.0},{"type":"null"}],"title":"Patient Age"},"patient_sex":{"anyOf":[{"type":"string","pattern":"^[MFmf]$"},{"type":"null"}],"title":"Patient Sex"},"trimester":{"anyOf":[{"type":"integer","maximum":3.0,"minimum":1.0},{"type":"null"}],"title":"Trimester","description":"Pregnancy trimester (1-3) for MCE trimester edits"},"setting":{"anyOf":[{"$ref":"#/components/schemas/CareSetting"},{"type":"null"}],"description":"Care setting of the encounter (the RA lane's CareSetting vocabulary). When the `coding_v2_setting_axis` flag is on it decides the uncertain-diagnosis rule: `inpatient_acute` applies ICD-10-CM Guideline II.H (code probable/suspected diagnoses as if established); every other setting applies Guideline IV.H (do not code them; code the symptoms). Absent keeps `code_uncertain_diagnoses` deciding."}},"type":"object","title":"EncounterMetadata","description":"Optional encounter context for denial-prevention rules."},"EvidencePermission":{"type":"string","enum":["establish_diagnosis","corroborate_documented","support_specificity","contradict","test_result_only","never_establish_alone"],"title":"EvidencePermission","description":"What a subtype is permitted to DO with a diagnosis, per program."},"EvidenceSpan":{"properties":{"span_text":{"type":"string","title":"Span Text"},"concept":{"type":"string","title":"Concept"},"char_start":{"type":"integer","title":"Char Start"},"char_end":{"type":"integer","title":"Char End"},"document_regions":{"items":{"$ref":"#/components/schemas/DocumentRegion"},"type":"array","title":"Document Regions"}},"type":"object","required":["span_text","concept","char_start","char_end","document_regions"],"title":"EvidenceSpan","description":"A verbatim chart span behind a code, with its coordinates."},"ExpandRequest":{"properties":{"text":{"type":"string","maxLength":10000,"minLength":1,"title":"Text","description":"Text containing abbreviations to expand"}},"type":"object","required":["text"],"title":"ExpandRequest","description":"Request body for abbreviation expansion."},"ExpandTermRequest":{"properties":{"term":{"type":"string","maxLength":100,"minLength":1,"title":"Term","description":"Single abbreviation to expand"}},"type":"object","required":["term"],"title":"ExpandTermRequest","description":"Request body for single term expansion."},"FlushResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"children_billed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Children Billed"},"events_reported":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Events Reported"},"units_reported":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Units Reported"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"additionalProperties":true,"type":"object","required":["success"],"title":"FlushResponse"},"ForgotPasswordRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"}},"type":"object","required":["email"],"title":"ForgotPasswordRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IngestLimitsInput":{"properties":{"max_bytes":{"type":"integer","title":"Max Bytes"},"max_pages":{"type":"integer","title":"Max Pages"},"max_pixels":{"type":"integer","title":"Max Pixels"},"max_archive_expansion_ratio":{"type":"number","title":"Max Archive Expansion Ratio"},"max_archive_depth":{"type":"integer","title":"Max Archive Depth"}},"type":"object","required":["max_bytes","max_pages","max_pixels","max_archive_expansion_ratio","max_archive_depth"],"title":"IngestLimitsInput","description":"A1.1 resource limits for the upload. Note what is absent: there is no \"process only\nthe first N pages\" knob — a page cap REJECTS the upload loudly, because silently\ntruncating a chart is precisely the silent-loss shape A1 exists to prevent."},"InpatientCodeRequest":{"properties":{"chart_text":{"type":"string","maxLength":200000,"minLength":1,"title":"Chart Text","description":"Inpatient chart. ⚠ PHI."},"encounter":{"$ref":"#/components/schemas/EncounterIn"},"principal_dx":{"anyOf":[{"$ref":"#/components/schemas/DiagnosisIn"},{"type":"null"}],"description":"Optional. With it (and every diagnosis carrying POA) the response adds the MS-DRG and a grouper-grounded principal procedure."},"secondary_dx":{"items":{"$ref":"#/components/schemas/DiagnosisIn"},"type":"array","maxItems":24,"title":"Secondary Dx"}},"type":"object","required":["chart_text","encounter"],"title":"InpatientCodeRequest"},"InviteMemberRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"role":{"type":"string","title":"Role","default":"viewer"}},"type":"object","required":["email"],"title":"InviteMemberRequest"},"JobCreatedResponse":{"properties":{"job_id":{"type":"string","title":"Job Id"},"status":{"type":"string","title":"Status","default":"pending"}},"type":"object","required":["job_id"],"title":"JobCreatedResponse"},"LinkView":{"properties":{"customer_org_id":{"type":"string","title":"Customer Org Id"},"status":{"type":"string","title":"Status"},"commission_model":{"type":"string","title":"Commission Model"},"margin_bps":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Margin Bps"},"flat_per_unit_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Flat Per Unit Cents"},"billing_responsibility":{"type":"string","title":"Billing Responsibility"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"customer_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Slug"},"customer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Name"},"customer_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Tier"}},"additionalProperties":true,"type":"object","required":["customer_org_id","status","commission_model","margin_bps","flat_per_unit_cents","billing_responsibility","created_at"],"title":"LinkView"},"LoginRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"password":{"type":"string","title":"Password"},"mfa_code":{"anyOf":[{"type":"string","maxLength":12},{"type":"null"}],"title":"Mfa Code"}},"type":"object","required":["email","password"],"title":"LoginRequest"},"MFADisableRequest":{"properties":{"password":{"type":"string","title":"Password"},"code":{"type":"string","maxLength":12,"minLength":6,"title":"Code"}},"type":"object","required":["password","code"],"title":"MFADisableRequest"},"MFAVerifyRequest":{"properties":{"code":{"type":"string","maxLength":12,"minLength":6,"title":"Code"}},"type":"object","required":["code"],"title":"MFAVerifyRequest"},"Modality":{"type":"string","enum":["in_person_face_to_face","telehealth_synchronous_audio_video","telehealth_audio_only","telehealth_modality_unspecified","asynchronous","modality_unresolved","modality_conflict"],"title":"Modality"},"ModalityEvidenceInput":{"properties":{"pos_codes":{"items":{"type":"string"},"type":"array","title":"Pos Codes","description":"Documented CMS place-of-service codes. 02 = telehealth other than in the patient's home, 10 = telehealth in the home; any other POS is simply not a telehealth signal. Matched EXACTLY — send the canonical two-character code."},"cpt_modifiers":{"items":{"type":"string"},"type":"array","title":"Cpt Modifiers","description":"Documented CPT/HCPCS modifiers. 95 = synchronous audio-video, 93 and FQ = audio-only, FR = practitioner present by real-time video. Matched EXACTLY, uppercase and unpadded. 93/FQ together with 95 is a modality CONFLICT, not a tie-break — the encounter goes to the evidence lane."},"narrative_telehealth_cue":{"type":"boolean","title":"Narrative Telehealth Cue","description":"The note itself STATES the visit was conducted by telehealth. This is a documented statement, never an inference from a missing physical exam.","default":false},"narrative_audio_only_cue":{"type":"boolean","title":"Narrative Audio Only Cue","description":"The note STATES the visit was audio-only (telephone). Leave it false when unstated: the encounter is then typed telehealth_modality_unspecified, which no program accepts for submission, rather than silently promoted to audio-video.","default":false},"face_to_face_attestation":{"type":"boolean","title":"Face To Face Attestation","description":"A documented in-person face-to-face attestation. Sent together with a telehealth signal it is a modality CONFLICT — the two claims are not reconciled.","default":false}},"type":"object","title":"ModalityEvidenceInput","description":"A4.13 modality evidence — the observed facts A4 DETERMINES the encounter's modality\nfrom, and that A5/A7 then resolve program eligibility against.\n\nAbsent this bundle A4 sees an empty evidence set, and the project pack's\n``presume_in_person_absent_telehealth`` knob turns that silence into\n``in_person_face_to_face``. So a caller with a telehealth encounter had no way to say\nso, and the gate's modality rule was applied to a presumed modality rather than a\ndocumented one.\n\nEvidence is GATHERED here, never guessed: A4 reads exactly these values and derives\nnothing on its own. In particular ``narrative_*`` are things the note SAYS, not\nconclusions drawn from what it omits, and audio-video is never assumed when a\ntelehealth encounter does not state which it was."},"ModelBindingInput":{"properties":{"program_id":{"type":"string","title":"Program Id"},"payment_year":{"type":"integer","title":"Payment Year"},"diagnosis_data_year":{"type":"integer","title":"Diagnosis Data Year"},"model_pack_id":{"type":"string","title":"Model Pack Id"},"organization_type":{"$ref":"#/components/schemas/OrganizationType"},"benefit_type":{"$ref":"#/components/schemas/BenefitType"},"model_family":{"$ref":"#/components/schemas/ModelFamily"},"model_version":{"type":"string","title":"Model Version"},"calibration_version":{"type":"string","title":"Calibration Version"},"run_variant":{"$ref":"#/components/schemas/RunVariant"},"diagnosis_source_policy_id":{"type":"string","title":"Diagnosis Source Policy Id"},"source_policy_organization_type":{"$ref":"#/components/schemas/OrganizationType"},"mapping_version":{"type":"string","title":"Mapping Version"},"mapping_run_variant":{"$ref":"#/components/schemas/RunVariant"},"software_version":{"type":"string","title":"Software Version"},"software_run_variant":{"$ref":"#/components/schemas/RunVariant"},"hierarchy_model_version":{"type":"string","title":"Hierarchy Model Version"},"coefficient_model_version":{"type":"string","title":"Coefficient Model Version"},"normalization_version":{"type":"string","title":"Normalization Version"},"policy_announcement_version":{"type":"string","title":"Policy Announcement Version"},"artifact_hashes":{"items":{"type":"string"},"type":"array","title":"Artifact Hashes"}},"type":"object","required":["program_id","payment_year","diagnosis_data_year","model_pack_id","organization_type","benefit_type","model_family","model_version","calibration_version","run_variant","diagnosis_source_policy_id","source_policy_organization_type","mapping_version","mapping_run_variant","software_version","software_run_variant","hierarchy_model_version","coefficient_model_version","normalization_version","policy_announcement_version","artifact_hashes"],"title":"ModelBindingInput","description":"The exact D-stage run identity: model / calibration / mapping / software / hierarchy\n/ coefficient / normalization / policy-announcement versions plus the artifact hashes.\nMixing incompatible components is refused at construction (an initial mapping on final\nsoftware, a V28 hierarchy with V24 coefficients, a bare unhashed bundle)."},"ModelFamily":{"type":"string","enum":["CMS-HCC","ESRD","RxHCC","PACE","HHS-HCC"],"title":"ModelFamily","description":"RA model families — never added together; each has its own adapter (Phase D)."},"NoteRequest":{"properties":{"note":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Note"}},"type":"object","title":"NoteRequest"},"ObservedUploadInput":{"properties":{"byte_size":{"type":"integer","title":"Byte Size"},"page_count":{"type":"integer","title":"Page Count"},"pixel_count":{"type":"integer","title":"Pixel Count"},"archive_expansion_ratio":{"type":"number","title":"Archive Expansion Ratio"},"archive_depth":{"type":"integer","title":"Archive Depth"}},"type":"object","required":["byte_size","page_count","pixel_count","archive_expansion_ratio","archive_depth"],"title":"ObservedUploadInput","description":"The observed facts about the upload that A1.1 checks against the limits. A filename\nor an extension is deliberately not among them — neither is a parameter any decision\nin A1 is allowed to read."},"OpenAIFunctionCall":{"properties":{"name":{"type":"string","title":"Name","description":"Function name"},"arguments":{"type":"string","title":"Arguments","description":"JSON-encoded arguments"}},"type":"object","required":["name","arguments"],"title":"OpenAIFunctionCall","description":"OpenAI function call format."},"OpenAIToolCallRequest":{"properties":{"id":{"type":"string","title":"Id","description":"Tool call ID from OpenAI response"},"type":{"type":"string","title":"Type","description":"Tool type","default":"function"},"function":{"$ref":"#/components/schemas/OpenAIFunctionCall","description":"Function details"}},"type":"object","required":["id","function"],"title":"OpenAIToolCallRequest","description":"Request for executing an OpenAI tool call."},"OrgEnvelope":{"properties":{"success":{"type":"boolean","title":"Success"},"org":{"$ref":"#/components/schemas/OrgView"}},"additionalProperties":true,"type":"object","required":["success","org"],"title":"OrgEnvelope"},"OrgListResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"orgs":{"items":{"$ref":"#/components/schemas/OrgView"},"type":"array","title":"Orgs"}},"additionalProperties":true,"type":"object","required":["success","orgs"],"title":"OrgListResponse"},"OrgView":{"properties":{"id":{"type":"string","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"tier":{"type":"string","title":"Tier"},"billing_provider":{"type":"string","title":"Billing Provider"},"region":{"type":"string","title":"Region"},"baa_signed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Baa Signed At"},"branding":{"anyOf":[{"$ref":"#/components/schemas/BrandingView"},{"type":"null"}]},"your_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Your Role"},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role"},"is_reseller":{"type":"boolean","title":"Is Reseller"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"additionalProperties":true,"type":"object","required":["id","slug","name","tier","billing_provider","region","baa_signed_at","branding","your_role","role","is_reseller","created_at"],"title":"OrgView"},"OrganizationType":{"type":"string","enum":["non_pace","pace"],"title":"OrganizationType"},"PolicyStampInput":{"properties":{"artifact_ref":{"type":"string","title":"Artifact Ref"},"document_subtype":{"$ref":"#/components/schemas/DocumentSubtype"},"clinical_role":{"$ref":"#/components/schemas/ClinicalRole"},"author_role":{"$ref":"#/components/schemas/AuthorRole"},"lifecycle":{"$ref":"#/components/schemas/DocumentLifecycle"},"program":{"$ref":"#/components/schemas/ProgramNamespace"},"rule_version":{"type":"string","title":"Rule Version"},"potential_role":{"$ref":"#/components/schemas/PotentialRole"},"client_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Id","description":"Required for client_specific stamps, forbidden for official programs."},"remaining_requirements":{"items":{"$ref":"#/components/schemas/RemainingRequirement"},"type":"array","title":"Remaining Requirements"},"evidence_permissions":{"items":{"$ref":"#/components/schemas/EvidencePermission"},"type":"array","title":"Evidence Permissions"},"evidence_span_refs":{"items":{"type":"string"},"type":"array","title":"Evidence Span Refs"},"detail":{"type":"string","title":"Detail","default":""}},"type":"object","required":["artifact_ref","document_subtype","clinical_role","author_role","lifecycle","program","rule_version","potential_role"],"title":"PolicyStampInput","description":"A3 §2 — one artifact, one program, one POTENTIAL role.\n\nThe stamp carries the four facts it is JUDGED on rather than a caller's word that the\nceiling was checked upstream: A3 re-derives the ceiling from them, so a stamp may only\nnarrow it, never broaden it. A caller cannot promote a nurse's note to a primary\nsource by asking nicely."},"PotentialRole":{"type":"string","enum":["potential_primary_source","potential_supporting_evidence","manifest_only","blocked_unclassified"],"title":"PotentialRole","description":"A3 stamps a POTENTIAL role. Note what is absent: no ``eligible``,\n``qualified``, or ``certified`` member exists — A3 certifies nothing."},"ProgramModalityRuleInput":{"properties":{"program":{"type":"string","title":"Program"},"rule_version":{"type":"string","title":"Rule Version"},"effective_from":{"type":"string","format":"date","title":"Effective From"},"acceptable_modalities":{"items":{"$ref":"#/components/schemas/Modality"},"type":"array","title":"Acceptable Modalities"},"effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Effective To"}},"type":"object","required":["program","rule_version","effective_from","acceptable_modalities"],"title":"ProgramModalityRuleInput","description":"The effective-dated program modality artifact A5/A7 resolve eligibility against. An\nempty ``acceptable_modalities`` is refused at construction: it is indistinguishable\nfrom a missing rule, and a missing rule has to block loudly rather than quietly\naccept everything."},"ProgramNamespace":{"type":"string","enum":["medicare_advantage_cms_hcc","rx_hcc","esrd","pace","hhs_hcc","client_specific"],"title":"ProgramNamespace","description":"Isolated program namespaces.\n\nNote what is ABSENT and unconstructible: a generic ``risk_adjustment`` namespace.\nEvery rule belongs to one named program with its own effective-dated pack — there\nis no bucket in which a CMS-HCC ruling can be mistaken for an HHS-HCC one."},"ProviderCandidateInput":{"properties":{"provider_id":{"type":"string","title":"Provider Id"},"roles":{"items":{"$ref":"#/components/schemas/ProviderRole"},"type":"array","title":"Roles"},"provider_type":{"$ref":"#/components/schemas/ProviderType"},"signature":{"$ref":"#/components/schemas/SignatureAttestationInput"},"credential_evidence_span":{"type":"string","title":"Credential Evidence Span","default":""},"specialty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Specialty"}},"type":"object","required":["provider_id","roles","provider_type","signature"],"title":"ProviderCandidateInput","description":"One documented provider on the encounter. A6 binds the accountable one against the\nCMS Acceptable Physician Specialty Types list for the DOS's payment year — a year that\nwas never loaded is UNDETERMINABLE, which the gate must not read as acceptable."},"ProviderPath":{"type":"string","enum":["structured","chart_chase"],"title":"ProviderPath","description":"Which §A6.2 acceptability path binds this encounter's provider check."},"ProviderRole":{"type":"string","enum":["attending","author","signer","co_signer","rendering","consultant","ordering","interpreting","supervising","referring","billing","scribe"],"title":"ProviderRole","description":"The A4.10 role-candidate vocabulary. A4 attributes them; A6 decides."},"ProviderType":{"type":"string","enum":["physician","nurse_practitioner","physician_assistant","clinical_nurse_specialist","certified_nurse_midwife","psychologist","registered_nurse","therapist","technologist","facility_staff","patient","provider_type_not_documented"],"title":"ProviderType","description":"Provider/author types (§A3 ``author_role``, §D9 credentials).\n\nWhich of these is ACCEPTABLE is program policy, supplied per call — this module\nhardcodes no acceptable set."},"ProvisionCustomerRequest":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"tier":{"type":"string","title":"Tier","default":"free"},"margin_bps":{"anyOf":[{"type":"integer","maximum":10000.0,"minimum":0.0},{"type":"null"}],"title":"Margin Bps"},"commission_model":{"type":"string","title":"Commission Model","default":"margin"},"flat_per_unit_cents":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Flat Per Unit Cents"},"billing_responsibility":{"type":"string","title":"Billing Responsibility","default":"reseller"},"create_api_key":{"type":"boolean","title":"Create Api Key","default":true}},"type":"object","required":["name"],"title":"ProvisionCustomerRequest"},"ProvisionCustomerResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"customer":{"$ref":"#/components/schemas/CustomerSummary"},"link":{"$ref":"#/components/schemas/LinkView"},"api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},"additionalProperties":true,"type":"object","required":["success","customer","link","api_key"],"title":"ProvisionCustomerResponse"},"PurgeOrgDataRequest":{"properties":{"confirm":{"type":"string","maxLength":200,"minLength":1,"title":"Confirm"}},"type":"object","required":["confirm"],"title":"PurgeOrgDataRequest","description":"The org's slug or id, typed back, so a stray DELETE cannot destroy a tenant."},"RaCodeRequest":{"properties":{"text":{"anyOf":[{"type":"string","maxLength":200000},{"type":"null"}],"title":"Text","description":"Chart / note text"},"document_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Base64","description":"Base64 of a raw chart file (PDF/image) — OCR'd to text first"},"document_content_type":{"type":"string","title":"Document Content Type","description":"MIME of document_base64 (for the OCR layer)","default":"application/pdf"},"tenant_id":{"type":"string","minLength":1,"title":"Tenant Id"},"project_id":{"type":"string","minLength":1,"title":"Project Id"},"encounter_id":{"type":"string","minLength":1,"title":"Encounter Id","default":"encounter-1"},"member_ref":{"type":"string","minLength":1,"title":"Member Ref","description":"Authoritative unique member reference (A2 identity)"},"setting":{"type":"string","title":"Setting","description":"office | inpatient | hospital_outpatient | observation | emergency_department","default":"office"},"service_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Service Date"},"discharge_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Discharge Date"},"collection_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Collection Date"},"program_ids":{"items":{"type":"string"},"type":"array","title":"Program Ids"},"compute_raf":{"type":"boolean","title":"Compute Raf","default":false},"demographics":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Demographics","description":"RAF inputs (dob/sex/orec/enrollment_segment …); enrollment_segment must be a V28 model-segment code when a payment RAF is wanted."},"document_evidence":{"anyOf":[{"$ref":"#/components/schemas/DocumentEvidenceInput"},{"type":"null"}],"description":"A1 integrity + A3 typing evidence. Runs the document front-door before anything else and derives the documented A7 source role."},"modality_evidence":{"anyOf":[{"$ref":"#/components/schemas/ModalityEvidenceInput"},{"type":"null"}],"description":"A4.13 evidence for HOW the encounter was conducted (POS codes, CPT modifiers, narrative cues, a face-to-face attestation). Without it A4 has no evidence and the project pack's presume_in_person_absent_telehealth knob decides the modality — so a telehealth encounter cannot be stated, and the gate resolves the program's telehealth rule against a presumption."},"gate_evidence":{"anyOf":[{"$ref":"#/components/schemas/EncounterGateEvidenceInput"},{"type":"null"}],"description":"A5/A6/A7 encounter-eligibility evidence (care setting, provider, signature, modality rule). Requires the A-stage intake this endpoint always supplies; without it no encounter-level gate runs. The modality it resolves is A4's determination from modality_evidence — this bundle never re-determines it."},"score_layer_evidence":{"anyOf":[{"$ref":"#/components/schemas/ScoreLayerEvidenceInput"},{"type":"null"}],"description":"D3→D8 official CMS artifacts. Only with these — and compute_raf — does the raw V28 score become the payment RAF; otherwise payment_raf stays null."}},"type":"object","required":["tenant_id","project_id","member_ref"],"title":"RaCodeRequest","description":"One encounter to code end-to-end through the RA pipeline.\n\nSupply ``text`` (a note/chart already in text) OR ``document_base64`` (a raw chart file,\nrun through OCR first). Member/encounter metadata is required — the pipeline binds identity\n(A2) and derives the release + perspective (A4) from it; it never invents them.\n\nFour optional evidence bundles each switch on a stage that is otherwise unreachable over\nHTTP, and each one absent leaves the pipeline exactly as it behaved before it existed:\n\n* ``document_evidence`` — A1 integrity + A3 typing (the document front door)\n* ``modality_evidence`` — A4.13, how the encounter was actually conducted\n* ``gate_evidence`` — A5/A6/A7 encounter eligibility\n* ``score_layer_evidence`` — D3→D8, the raw score → the payment RAF"},"RaCodeResponse":{"properties":{"status":{"type":"string","title":"Status"},"detail":{"type":"string","title":"Detail"},"codes":{"items":{"type":"string"},"type":"array","title":"Codes"},"principal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Principal Code"},"eligible_events":{"items":{"type":"string"},"type":"array","title":"Eligible Events"},"condition_routes":{"items":{"type":"string"},"type":"array","title":"Condition Routes"},"evidence":{"items":{"$ref":"#/components/schemas/CodeEvidenceItem"},"type":"array","title":"Evidence"},"segment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Segment"},"raf":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Raf"},"payment_raf":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Payment Raf"},"payment_raf_status":{"type":"string","title":"Payment Raf Status"},"document_disposition":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Disposition"},"encounter_gate":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Encounter Gate"},"ocr_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ocr Provider"},"stage_trace":{"items":{"type":"string"},"type":"array","title":"Stage Trace"},"release_bundle_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Release Bundle Id"},"modality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modality"},"read_failure":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Read Failure"},"findings":{"items":{"type":"string"},"type":"array","title":"Findings"},"dropped_ungrounded":{"items":{"type":"string"},"type":"array","title":"Dropped Ungrounded"},"ungrounded_normalizations":{"items":{"type":"string"},"type":"array","title":"Ungrounded Normalizations"},"completion_statuses":{"items":{"type":"string"},"type":"array","title":"Completion Statuses"},"remediation_requests":{"items":{"type":"string"},"type":"array","title":"Remediation Requests"},"integrality_decisions":{"items":{"type":"string"},"type":"array","title":"Integrality Decisions"},"hcc_dispositions":{"items":{"type":"string"},"type":"array","title":"Hcc Dispositions"},"mapping_records":{"items":{"type":"string"},"type":"array","title":"Mapping Records"},"raf_status":{"type":"string","title":"Raf Status"},"zero_score_proof":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zero Score Proof"},"payment_raf_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Raf Label"},"document_source_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Source Role"},"encounter_gate_lane":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Encounter Gate Lane"},"encounter_gate_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Encounter Gate Reason"}},"type":"object","required":["status","detail","codes","principal_code","eligible_events","condition_routes","evidence","segment","raf","payment_raf","payment_raf_status","document_disposition","encounter_gate","ocr_provider","stage_trace","release_bundle_id","modality","read_failure","findings","dropped_ungrounded","ungrounded_normalizations","completion_statuses","remediation_requests","integrality_decisions","hcc_dispositions","mapping_records","raf_status","zero_score_proof","payment_raf_label","document_source_role","encounter_gate_lane","encounter_gate_reason"],"title":"RaCodeResponse","description":"The pipeline's audit surface, not a summary of it.\n\n⚠ API-H3: this model declared 15 fields while ``PipelineResult`` carries 30+, and a\npydantic ``response_model`` drops every undeclared key SILENTLY — no error, no warning,\nnothing in the payload saying anything was removed. So the C7 verification findings,\nthe B2 proposals whose own source comment promises they are \"visible, never silent\",\nthe HCC dispositions and mapping records, the legitimate-zero proof, the remediation\nrequests and the whole encounter-gate reason all died at the HTTP boundary. Widening\nit is additive: every field that was here keeps its name, type and meaning.\n\n``tests/test_ra_surface.py`` pins this field set against ``PipelineResult`` so the next\naudit field an author intends to expose cannot be eaten the same way.\n\nTwo ``PipelineResult`` fields are deliberately NOT here. ``member_ref`` is a member\nidentifier — PHI the caller already holds, and this endpoint does not echo one back,\nfor the same reason the §164.528 disclosure row logs the encounter id instead.\n``ledger`` is the internal F2 disposition object; its readable projection is already\nhere as ``findings`` + ``hcc_dispositions`` + ``completion_statuses``."},"RafDeltaRequest":{"properties":{"baseline_codes":{"items":{"type":"string"},"type":"array","maxItems":200,"title":"Baseline Codes","description":"Codes already accepted for the member"},"scenario_codes":{"items":{"type":"string"},"type":"array","maxItems":200,"title":"Scenario Codes","description":"Baseline plus the candidate(s) under consideration"},"model_family":{"type":"string","title":"Model Family","default":"CMS-HCC"},"model_version":{"type":"string","title":"Model Version","default":"V28"},"payment_year":{"type":"integer","maximum":2100.0,"minimum":2000.0,"title":"Payment Year","default":2026},"segment":{"type":"string","title":"Segment","description":"Scoring segment, e.g. COMMUNITY_NA","default":"COMMUNITY_NA"},"demographics":{"anyOf":[{"$ref":"#/components/schemas/Demographics"},{"type":"null"}]},"demographics_override_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Demographics Override Reason"},"service_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Service Date","description":"Date of service. If given, the loaded pack's ICD fiscal-year mapping must cover it; otherwise 422 blocked_mapping_window_pending (never a number from the wrong year)."},"ndc_codes":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":500},{"type":"null"}],"title":"Ndc Codes","description":"HHS-HCC: dispensed National Drug Codes. Omit if unknown (the score then reports which factors it could not evaluate); send [] to assert there were none."},"hcpcs_codes":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":500},{"type":"null"}],"title":"Hcpcs Codes","description":"HHS-HCC: administered HCPCS codes. Omit if unknown; send [] to assert none."}},"type":"object","required":["scenario_codes"],"title":"RafDeltaRequest"},"RegisterDomainRequest":{"properties":{"hostname":{"type":"string","maxLength":253,"minLength":3,"title":"Hostname"}},"type":"object","required":["hostname"],"title":"RegisterDomainRequest"},"RegisterDomainResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"domain":{"$ref":"#/components/schemas/DomainView"},"verification_token":{"type":"string","title":"Verification Token"},"instructions":{"type":"string","title":"Instructions"}},"additionalProperties":true,"type":"object","required":["success","domain","verification_token","instructions"],"title":"RegisterDomainResponse"},"RegisterRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"password":{"type":"string","title":"Password"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"tos_version":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Tos Version"},"tos_accepted":{"type":"boolean","title":"Tos Accepted","default":false}},"type":"object","required":["email","password"],"title":"RegisterRequest"},"RemainingRequirement":{"type":"string","enum":["provider_source","provider_specialty","signature","face_to_face_or_qualifying_modality","date_of_service","eligible_service","qualifying_encounter_presence","provider_involvement","final_assessment_present"],"title":"RemainingRequirement","description":"What later stages must still satisfy. A3 leaves work behind, always."},"ReportMembersRequest":{"properties":{"period_year":{"type":"integer","maximum":2100.0,"minimum":2025.0,"title":"Period Year"},"period_month":{"type":"integer","maximum":12.0,"minimum":1.0,"title":"Period Month"},"member_count":{"type":"integer","minimum":0.0,"title":"Member Count"}},"type":"object","required":["period_year","period_month","member_count"],"title":"ReportMembersRequest"},"ResetPasswordRequest":{"properties":{"token":{"type":"string","title":"Token"},"new_password":{"type":"string","title":"New Password"}},"type":"object","required":["token","new_password"],"title":"ResetPasswordRequest"},"RotateKeyRequest":{"properties":{"grace_period_minutes":{"type":"integer","title":"Grace Period Minutes","default":60}},"type":"object","title":"RotateKeyRequest"},"RoundingRule":{"type":"string","enum":["half_up","half_even","truncate"],"title":"RoundingRule"},"RunVariant":{"type":"string","enum":["initial","midyear","final"],"title":"RunVariant"},"ScenarioRequest":{"properties":{"accept":{"items":{"type":"string"},"type":"array","title":"Accept","default":[]},"reject":{"items":{"type":"string"},"type":"array","title":"Reject","default":[]}},"type":"object","title":"ScenarioRequest"},"ScimListResponse":{"properties":{"schemas":{"items":{"type":"string"},"type":"array","title":"Schemas"},"totalResults":{"type":"integer","title":"Totalresults"},"startIndex":{"type":"integer","title":"Startindex"},"itemsPerPage":{"type":"integer","title":"Itemsperpage"},"Resources":{"items":{"$ref":"#/components/schemas/ScimUserResource"},"type":"array","title":"Resources","default":[]}},"additionalProperties":true,"type":"object","required":["schemas","totalResults","startIndex","itemsPerPage"],"title":"ScimListResponse","description":"OpenAPI shape of a SCIM ListResponse (see ``list_users``)."},"ScimServiceProviderConfig":{"properties":{"schemas":{"items":{"type":"string"},"type":"array","title":"Schemas"}},"additionalProperties":true,"type":"object","required":["schemas"],"title":"ScimServiceProviderConfig","description":"OpenAPI shape of the SCIM ServiceProviderConfig (see ``service_provider_config``)."},"ScimTokenResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"scim_token":{"type":"string","title":"Scim Token"},"scim_base_url":{"type":"string","title":"Scim Base Url"},"note":{"type":"string","title":"Note"}},"additionalProperties":true,"type":"object","required":["success","scim_token","scim_base_url","note"],"title":"ScimTokenResponse"},"ScimUserResource":{"properties":{"schemas":{"items":{"type":"string"},"type":"array","title":"Schemas"},"id":{"type":"string","title":"Id"},"userName":{"type":"string","title":"Username"},"active":{"type":"boolean","title":"Active"},"displayName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Displayname"},"name":{"additionalProperties":true,"type":"object","title":"Name","default":{}},"emails":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Emails","default":[]},"meta":{"additionalProperties":true,"type":"object","title":"Meta","default":{}}},"additionalProperties":true,"type":"object","required":["schemas","id","userName","active"],"title":"ScimUserResource","description":"OpenAPI shape of a SCIM User resource (see ``_scim_user``)."},"ScoreApplicability":{"type":"string","enum":["applicable_payment_run","simulation_only"],"title":"ScoreApplicability","description":"Parallel runs are fine for analytics — only the APPLICABLE output is a payment\nfactor. A ``simulation_only`` value is ``not_used_for_payment`` everywhere it\ntravels, because the tag rides on the envelope and the envelope is inherited."},"ScoreLayerEvidenceInput":{"properties":{"binding":{"$ref":"#/components/schemas/ModelBindingInput"},"normalization_factor":{"type":"number","title":"Normalization Factor"},"policy_pack_id":{"type":"string","title":"Policy Pack Id"},"input_snapshot_hash":{"type":"string","title":"Input Snapshot Hash"},"precision":{"type":"integer","title":"Precision","default":3},"rounding_rule":{"$ref":"#/components/schemas/RoundingRule","default":"half_even"},"calculation_mode":{"$ref":"#/components/schemas/CalculationMode","default":"internal_projection"},"applicability":{"$ref":"#/components/schemas/ScoreApplicability","default":"applicable_payment_run"}},"type":"object","required":["binding","normalization_factor","policy_pack_id","input_snapshot_hash"],"title":"ScoreLayerEvidenceInput","description":"D3→D8 score-layer inputs. On a ``compute_raf`` run these complete the raw V28 score\ninto the actual payment RAF: D5 normalize → D6 blend → D7 the CY2026 MA coding-pattern\nreduction. Every value is an OFFICIAL effective-dated CMS artifact the caller supplies\n— a missing normalization factor is a typed block, never an implicit 1.0 — and the\nresult is labeled an INTERNAL projection, never the CMS-reported official factor.\n\nAbsent this bundle the pipeline stops at the raw score and ``payment_raf`` stays null,\nwhich is what it did for every request before this field existed."},"SearchMode":{"type":"string","enum":["index","tabular"],"title":"SearchMode"},"SessionMetadata":{"properties":{"patient_age":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Patient Age"},"patient_sex":{"anyOf":[{"type":"string","pattern":"^[MFmf]$"},{"type":"null"}],"title":"Patient Sex"},"encounter_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Encounter Type"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","title":"SessionMetadata"},"SettingsPatch":{"properties":{"review_mode_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Review Mode Enabled"},"require_mfa":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Require Mfa"},"avg_base_payment_dollars":{"anyOf":[{"type":"number","maximum":1000000.0,"minimum":0.0},{"type":"null"}],"title":"Avg Base Payment Dollars"},"autonomous_threshold":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Autonomous Threshold"},"autonomous_blocking_severity":{"anyOf":[{"type":"string","pattern":"^(error|warning|info)$"},{"type":"null"}],"title":"Autonomous Blocking Severity"},"preferred_hcc_model_version":{"anyOf":[{"type":"string","pattern":"^(V24|V28)$"},{"type":"null"}],"title":"Preferred Hcc Model Version"},"preferred_hcc_segment":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Preferred Hcc Segment"},"session_idle_timeout_minutes":{"anyOf":[{"type":"integer","maximum":720.0,"minimum":1.0},{"type":"null"}],"title":"Session Idle Timeout Minutes"}},"type":"object","title":"SettingsPatch","description":"Fields the storefront can flip from the account page."},"SettingsResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"data":{"$ref":"#/components/schemas/SettingsView"}},"additionalProperties":true,"type":"object","required":["success","data"],"title":"SettingsResponse","description":"Envelope returned by GET/PATCH /org/settings."},"SettingsView":{"properties":{"id":{"type":"string","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"review_mode_enabled":{"type":"boolean","title":"Review Mode Enabled"},"require_mfa":{"type":"boolean","title":"Require Mfa","default":false},"avg_base_payment_dollars":{"type":"number","title":"Avg Base Payment Dollars"},"autonomous_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Autonomous Threshold"},"autonomous_blocking_severity":{"type":"string","title":"Autonomous Blocking Severity"},"preferred_hcc_model_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preferred Hcc Model Version"},"preferred_hcc_segment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preferred Hcc Segment"}},"additionalProperties":true,"type":"object","required":["id","slug","name","review_mode_enabled","avg_base_payment_dollars","autonomous_threshold","autonomous_blocking_severity","preferred_hcc_model_version","preferred_hcc_segment"],"title":"SettingsView","description":"Shape of the settings payload returned by GET/PATCH /org/settings.\n\n``extra=\"allow\"`` keeps any field returned by ``_settings_view`` that\nisn't declared here — this model documents the response in OpenAPI\nwithout dropping data."},"SignatureAttestationInput":{"properties":{"signed":{"type":"boolean","title":"Signed"},"signature_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Signature Date"},"evidence_span":{"type":"string","title":"Evidence Span"},"method":{"anyOf":[{"$ref":"#/components/schemas/AuthenticationMethod"},{"type":"null"}]},"disability_accommodation":{"type":"boolean","title":"Disability Accommodation","description":"A signature STAMP is rejected unless this is documented.","default":false}},"type":"object","required":["signed","signature_date","evidence_span"],"title":"SignatureAttestationInput","description":"A6 signature evidence. An unsigned or undated note is ``blocked_remediable`` — a\ndefect a provider can cure with an authenticated amendment — never a silent pass."},"SignupRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"}},"type":"object","required":["email"],"title":"SignupRequest"},"SourceRole":{"type":"string","enum":["potential_primary_source","potential_supporting_evidence","manifest_only","blocked_unclassified"],"title":"SourceRole","description":"A3's per-program potential-role stamp, carried into the A7 gate."},"SubmitCPTRequest":{"properties":{"cpt_code":{"type":"string","title":"Cpt Code"},"ai_metadata":{"anyOf":[{"$ref":"#/components/schemas/CPTAIMetadata"},{"type":"null"}]}},"type":"object","required":["cpt_code"],"title":"SubmitCPTRequest"},"ToolCallRequest":{"properties":{"name":{"type":"string","title":"Name","description":"Tool name to execute"},"arguments":{"additionalProperties":true,"type":"object","title":"Arguments","description":"Tool arguments","default":{}}},"type":"object","required":["name"],"title":"ToolCallRequest","description":"Request body for tool execution."},"TurnRequest":{"properties":{"condition":{"type":"string","maxLength":2000,"minLength":1,"title":"Condition","description":"Natural-language condition to code on this turn"},"year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year"},"include_hcc":{"type":"boolean","title":"Include Hcc","default":false}},"type":"object","required":["condition"],"title":"TurnRequest"},"UpdateLinkRequest":{"properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"margin_bps":{"anyOf":[{"type":"integer","maximum":10000.0,"minimum":0.0},{"type":"null"}],"title":"Margin Bps"},"commission_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Commission Model"},"flat_per_unit_cents":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Flat Per Unit Cents"},"billing_responsibility":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Billing Responsibility"}},"type":"object","title":"UpdateLinkRequest"},"UpdateLinkResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"link":{"$ref":"#/components/schemas/LinkView"}},"additionalProperties":true,"type":"object","required":["success","link"],"title":"UpdateLinkResponse"},"UpdateMeatProfileRequest":{"properties":{"criteria_required":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Criteria Required"},"evidence_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evidence Format"},"evidence_granularity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evidence Granularity"},"confidence_reporting":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Confidence Reporting"},"custom_extensions":{"anyOf":[{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array"},{"type":"null"}],"title":"Custom Extensions"}},"type":"object","title":"UpdateMeatProfileRequest"},"UpdateMemberRequest":{"properties":{"dob":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dob","description":"ISO-8601 date string"},"sex":{"anyOf":[{"type":"string","pattern":"^(M|F|O|U)$"},{"type":"null"}],"title":"Sex"},"plan_id":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Plan Id"},"enrollment_segment":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Enrollment Segment"},"notes":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Notes"}},"type":"object","title":"UpdateMemberRequest"},"UpdateOrgRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name"},"branding":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Branding"}},"type":"object","title":"UpdateOrgRequest"},"UpdatePolicyRequest":{"properties":{"policy":{"additionalProperties":true,"type":"object","title":"Policy"}},"type":"object","required":["policy"],"title":"UpdatePolicyRequest"},"UpdateProfileRequest":{"properties":{"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"}},"type":"object","title":"UpdateProfileRequest"},"UpdateRoleRequest":{"properties":{"role":{"type":"string","title":"Role"}},"type":"object","required":["role"],"title":"UpdateRoleRequest"},"UpdateWebhookRequest":{"properties":{"url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Url"},"events":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Events"},"active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Active"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","title":"UpdateWebhookRequest"},"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"},"VerifyEmailRequest":{"properties":{"token":{"type":"string","title":"Token"}},"type":"object","required":["token"],"title":"VerifyEmailRequest"},"WritebackRequest":{"properties":{"code":{"type":"string","maxLength":10,"minLength":1,"title":"Code"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description"},"confidence":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Confidence"}},"type":"object","required":["code"],"title":"WritebackRequest"}}}}