{ "openapi": "3.1.0", "info": { "title": "Auth57 API", "version": "1.0.0", "summary": "Verified prior-authorization rule data for all 51 US states.", "description": "Auth57 is a commercial REST API returning human-verified, source-linked prior-authorization (PA) rules across all 51 states, 7 programs, 20 service categories, and 20 drug classes.\n\nData is continuously updated via the Watch pipeline and benchmarked against CMS-0057-F and CMS-0062-P. Every response includes the source URL and `last_verified` date for citable use in clinical, compliance, and benefits workflows.\n\n## Authentication\n\nAll requests require an API key passed as `x-api-key`. Keys are issued per subscription. Request a paid key at https://auth57.io/subscribe-api or free demo access via https://auth57.io/book.\n\n## Rate limits\n\n- `/v1/pauth-lookup`: 10,000 requests per hour per API key\n- `/v1/compare`: 2,000 requests per hour per API key\n\nExceeding the limit returns HTTP 429 with a `Retry-After` header. Admin keys bypass limits.\n\n## Latency\n\nMost requests complete in under 200ms via the edge static fast path. The `served_from` field in the response tells you which path handled your call (`static` = edge CDN, `edge` = live Supabase query).\n\n## Support\n\nEmail hello@auth57labs.com or book a 30-min call at https://auth57.io/book.", "contact": { "name": "Auth57 Labs", "email": "hello@auth57labs.com", "url": "https://auth57labs.com" }, "license": { "name": "Commercial", "url": "https://auth57.io/terms" }, "termsOfService": "https://auth57.io/terms" }, "servers": [ { "url": "https://api.auth57.io", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Lookup", "description": "Single-state PA rule lookup." }, { "name": "Compare", "description": "Cross-state PA rule comparison." }, { "name": "Metadata", "description": "State-level coverage and flags." }, { "name": "Discovery", "description": "Public capability descriptors. No authentication required." } ], "paths": { "/api/v1/compliance/{rule_id}": { "get": { "summary": "Per-jurisdiction compliance grid against a CMS rule.", "description": "For a given CMS announcement (CMS-0057-F, CMS-0062-P, etc.), computes each US jurisdiction's implementation status. Status values: `in_compliance`, `partial`, `overdue`, `not_yet_due`, `unknown`. Public — no API key required.", "operationId": "complianceByRuleId", "tags": [ "Metadata" ], "security": [], "parameters": [ { "name": "rule_id", "in": "path", "required": true, "description": "CMS rule identifier, e.g. `CMS-0057-F` or `CMS-0062-P`.", "schema": { "type": "string", "pattern": "^[A-Z0-9-]{3,32}$" } } ], "responses": { "200": { "description": "Compliance grid + summary counts." }, "400": { "description": "Invalid rule_id format." }, "404": { "description": "No announcement_events found for this rule_id." } } } }, "/v1/action-plan": { "get": { "summary": "Ranked next actions for a prior-auth decision.", "description": "Returns a transparent, cited, RANKED action plan (proceed / submit / appeal / request continued benefits / switch alternative / switch plan / pay out-of-pocket / escalate / wait) for a (state, program, drug|service|code), each action with a deadline, plain-English rationale, the signals that drove its score, and source citations.\n\nGoes beyond the yes/no verdict of /v1/pauth-lookup by combining the PA rule with the jurisdiction's appeal ladder, who-to-call contacts, upcoming change windows, and optional member context. Also returns a `provenance` block (verified-from-official-source vs estimate). Optional member-context inputs are a CONTROLLED vocabulary (no free text) so the PHI guard stays meaningful.\n\nAuth: `x-api-key` (live) or `x-demo-session` (UUID, demo).", "operationId": "actionPlan", "tags": [ "Lookup" ], "parameters": [ { "$ref": "#/components/parameters/State" }, { "$ref": "#/components/parameters/Program" }, { "$ref": "#/components/parameters/Drug" }, { "$ref": "#/components/parameters/Service" }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CPT/HCPCS procedure code; resolved to a service_category via the state PA list or CPT-range fallback. Provide exactly one of drug, service, or code." }, { "name": "denied", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Whether the request was already denied." }, { "name": "denial_basis", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "step_therapy", "not_medically_necessary", "missing_docs", "not_on_formulary", "other" ] }, "description": "Controlled denial reason." }, { "name": "denial_days_ago", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Integer days since the denial notice (NOT a date — keeps PHI out of the query string)." }, { "name": "urgency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "routine", "urgent" ] }, "description": "Routine or urgent (drives expedited-appeal deadlines)." }, { "name": "drug_cost_usd", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Approximate out-of-pocket cost; informs the pay-out-of-pocket option." }, { "name": "has_alternative", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "A clinical alternative exists." }, { "name": "alternative_no_pa", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "The alternative does not require PA." }, { "name": "open_enrollment_near", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Open enrollment is near (informs switch-plan option)." }, { "name": "recurring", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "This is a recurring/repeat denial." } ], "responses": { "200": { "description": "Ranked action plan with provenance, contacts, appeal path, and supporting criteria.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "state": { "type": "string" }, "program": { "type": "string" }, "query": { "type": "object", "additionalProperties": true }, "rule": { "type": [ "object", "null" ], "additionalProperties": true }, "action_plan": { "type": "object", "additionalProperties": true, "description": "ranked_actions[], primary, basis, contacts, state_specifics" }, "provenance": { "type": "object", "additionalProperties": true, "description": "verified, basis, label, confidence, last_verified, source_url" }, "supporting_criteria": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "grounding": { "type": "string", "enum": [ "semantic", "keyword" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/v1/ask": { "post": { "summary": "Free-text question against the verified PA corpus.", "description": "POSTs a natural-language question and returns a structured answer grounded in the verified corpus. Use this when the client doesn't yet know (state, program, drug|service); the server attempts to extract them and respond with a rule or a clarifying request.\n\nIntended for agent integrations and chat surfaces. Token budget per request is bounded; large transcripts should be chunked client-side.", "operationId": "ask", "tags": [ "Lookup" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "description": "Free-text question." }, "state": { "type": "string", "description": "Optional 2-letter state hint." }, "program": { "type": "string", "description": "Optional program hint." } } } } } }, "responses": { "200": { "description": "Structured answer + citations." }, "400": { "description": "Missing or malformed question." }, "401": { "description": "Missing or invalid `x-api-key`." } } } }, "/v1/cds-services": { "get": { "summary": "CDS Hooks service discovery.", "description": "CDS Hooks 1.0 discovery endpoint — lists the Auth57 clinical-decision-support services an EHR can invoke (e.g. order-sign / order-select PA guidance). Public, no authentication, edge-cached 1h. Part of the Da Vinci CRD/DTR/PAS alignment.", "operationId": "cdsServices", "tags": [ "Discovery" ], "security": [], "responses": { "200": { "description": "CDS Hooks service descriptor.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "services": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } } }, "/v1/compare": { "get": { "summary": "Compare a PA rule across multiple states.", "description": "Returns the verified PA rules for the same (program, drug_or_service) combination across up to 10 states in a single call. Response includes a divergence summary flagging outliers.\n\nRequires a Compare subscription or Compare add-on on your account. Specify exactly one of `drug` or `service`.\n\nRate limit: 2,000 requests per hour per API key.", "operationId": "compare", "tags": [ "Compare" ], "parameters": [ { "name": "states", "in": "query", "required": true, "description": "Comma-separated list of 2-10 USPS state abbreviations.", "schema": { "type": "string", "pattern": "^[A-Z]{2}(,[A-Z]{2}){1,9}$", "example": "TX,CA,OH,NY,FL" } }, { "$ref": "#/components/parameters/Program" }, { "$ref": "#/components/parameters/Drug" }, { "$ref": "#/components/parameters/Service" } ], "responses": { "200": { "description": "Compare succeeded. Returns per-state results plus divergence summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareResponse" }, "example": { "states": [ "TX", "CA", "OH", "NY", "FL" ], "program": "medicaid_mco", "query": { "drug_class": "glp1_weight_loss" }, "summary": { "total": 5, "require_pa": 4, "no_pa": 1, "divergence": true, "divergence_summary": "4 of 5 states require PA. OH is an outlier." }, "results": [ { "state_abbr": "TX", "pa_required": true, "pa_type": "full", "confidence": 0.9, "notes": "GLP-1s require PA for T2DM...", "source_url": "https://www.txvendordrug.com/formulary/prior-authorization", "last_verified": "2026-04-22" } ], "served_from": "api", "timestamp": "2026-04-23T15:44:12.103Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/v1/drug-crosswalk": { "get": { "summary": "Drug brand ↔ generic ↔ class crosswalk.", "description": "Resolves a drug class to its constituent brand/generic names (via RxNorm-backed `drug_ingredients`), or a brand/generic name back to its drug class. Use to normalize free-text drug inputs before calling `/v1/pauth-lookup`.", "operationId": "drugCrosswalk", "tags": [ "Discovery" ], "parameters": [ { "name": "class", "in": "query", "description": "drug_class_code to expand into brand/generic members.", "schema": { "type": "string" } }, { "name": "brand", "in": "query", "description": "Brand name to resolve to a drug_class_code.", "schema": { "type": "string" } }, { "name": "generic", "in": "query", "description": "Generic name to resolve to a drug_class_code.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response shape — `flat` (default) or `grouped`.", "schema": { "type": "string", "enum": [ "flat", "grouped" ] } } ], "responses": { "200": { "description": "Crosswalk rows." }, "400": { "description": "Provide exactly one of class/brand/generic." } } } }, "/v1/lookup-options": { "get": { "summary": "Available drug classes and service categories for a (state, program) pair.", "description": "Returns the subset of `drug_class_code` and `service_category` values that actually have published rules for the given (state, program) combination, each paired with a human-readable label suitable for dropdown UIs.\n\nUse this to populate dependent selectors — pick a state and program first, then call this endpoint to know which drug/service options will resolve in `/v1/pa-lookup`.\n\nNo authentication required. Cached at the edge for 5 minutes (`s-maxage=300`).", "operationId": "lookupOptions", "tags": [ "Discovery" ], "security": [], "parameters": [ { "name": "state", "in": "query", "required": true, "description": "USPS 2-letter state abbreviation.", "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "TX" } }, { "$ref": "#/components/parameters/Program" } ], "responses": { "200": { "description": "Available options. Both arrays may be empty if no rules are published for the (state, program) pair.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupOptionsResponse" }, "example": { "drugs": [ { "val": "glp1_weight_loss", "label": "GLP-1 — Weight Loss" }, { "val": "diabetes_insulin", "label": "Insulin / Diabetes" } ], "services": [ { "val": "advanced_imaging", "label": "Advanced Imaging" }, { "val": "inpatient_hospital", "label": "Inpatient Hospital" } ] } } } }, "400": { "description": "Missing or invalid `state` / `program`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "state and program required" } } } } } } }, "/v1/manifest": { "get": { "summary": "Dataset capability descriptor.", "description": "Returns a one-shot machine-readable description of what's available in the Auth57 corpus: total verified rule count, supported states / programs / drug classes / service categories, dataset version, last verification date, upcoming federal mandates, and pointers to other endpoints and documentation.\n\nIntentionally public (no `x-api-key` required) so SDKs and clients can discover capabilities before purchasing a subscription. Mirrors the well-known-endpoint pattern used by OAuth.\n\nCached at the edge for 1 hour (`s-maxage=3600`, `stale-while-revalidate=86400`).", "operationId": "manifest", "tags": [ "Discovery" ], "security": [], "responses": { "200": { "description": "Capability descriptor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManifestResponse" }, "example": { "service": "Auth57", "version": "1", "dataset": { "verified_rules": 1734, "service_rules": 612, "drug_rules": 1122, "last_verified": "2026-04-22" }, "coverage": { "states": [ "AL", "AK", "AZ", "AR", "CA" ], "states_count": 51, "programs": [ "medicaid_ffs", "medicaid_mco", "medicare_advantage", "medicare_traditional", "dual_eligible", "part_d", "chip" ], "service_categories": [ "advanced_imaging", "inpatient_hospital", "outpatient_surgery" ], "drug_classes": [ "biosimilars", "glp1_weight_loss", "specialty_biologics" ] }, "mandates": { "cms_0057_f": { "effective": "2027-01-01", "status": "final" }, "cms_0062_p": { "effective": "2027-10-01", "status": "proposed" } }, "endpoints": { "pa_lookup": "GET /v1/pa-lookup?state&program&drug|service", "compare": "GET /v1/compare?states&program&drug|service", "states": "GET /v1/states[?state=XX]", "manifest": "GET /v1/manifest", "lookup_options": "GET /v1/lookup-options?state&program" }, "docs": { "openapi": "https://auth57labs.com/openapi.json", "reference": "https://auth57labs.com/api-reference", "sdk": "https://www.npmjs.com/package/@auth57labs/sdk" } } } } } } } }, "/v1/metadata": { "get": { "summary": "FHIR CapabilityStatement.", "description": "FHIR R4 CapabilityStatement for the Auth57 FHIR surface — declares supported resources, operations, and the CRD/DTR/PAS interactions. Public, no authentication, returned as `application/fhir+json`, edge-cached 1h.", "operationId": "fhirMetadata", "tags": [ "Discovery" ], "security": [], "responses": { "200": { "description": "FHIR CapabilityStatement.", "content": { "application/fhir+json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "resourceType": { "type": "string", "example": "CapabilityStatement" } } } } } } } } }, "/v1/notify-when-ready": { "post": { "summary": "Subscribe to be notified when a coverage gap is filled.", "description": "Registers a request to be notified when Auth57 ingests a rule for a (state, program, drug|service) combination that currently returns a scope_gap 404. Lets clients turn a coverage miss into a demand signal + a future alert.", "operationId": "notifyWhenReady", "tags": [ "Metadata" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "state", "subject", "contact" ], "properties": { "state": { "type": "string", "description": "USPS 2-letter state." }, "program": { "type": "string", "description": "Program slug." }, "subject": { "type": "string", "description": "drug_class_code or service_category to watch." }, "kind": { "type": "string", "enum": [ "drug", "service" ], "default": "drug" }, "contact": { "type": "string", "description": "Email address or phone number." }, "channel": { "type": "string", "enum": [ "sms", "email" ], "default": "sms" } } } } } }, "responses": { "200": { "description": "Notification request recorded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/pa-lookup": { "get": { "summary": "Deprecated alias for /v1/pauth-lookup.", "description": "Returns the same payload as `/v1/pauth-lookup`. Kept for back-compat; prefer the canonical path in new integrations.", "operationId": "paLookupAlias", "deprecated": true, "tags": [ "Lookup" ], "parameters": [ { "$ref": "#/components/parameters/State" }, { "$ref": "#/components/parameters/Program" }, { "$ref": "#/components/parameters/Drug" }, { "$ref": "#/components/parameters/Service" } ], "responses": { "200": { "description": "Rule found. Response shape matches `/v1/pauth-lookup`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaLookupResponse" } } } }, "400": { "description": "Invalid parameters." }, "401": { "description": "Missing or invalid `x-api-key`." }, "404": { "description": "No verified rule for this (state, program, drug|service)." } } } }, "/v1/pauth-lookup": { "get": { "summary": "Look up a PA rule for one state / program / drug or service.", "description": "Returns the verified prior-authorization rule for a given (state, program, drug_or_service) combination. Specify exactly one of `drug` or `service`.\n\nResponses include the full rule plus a `next_steps` array of actionable items for the requestor (documentation to gather, submission target, expected turnaround).\n\nRate limit: 10,000 requests per hour per API key.\n\n`/v1/pa-lookup` is a deprecated alias for this endpoint and returns the same response.", "operationId": "pauthLookup", "tags": [ "Lookup" ], "parameters": [ { "$ref": "#/components/parameters/State" }, { "$ref": "#/components/parameters/Program" }, { "$ref": "#/components/parameters/Drug" }, { "$ref": "#/components/parameters/Service" } ], "responses": { "200": { "description": "Rule found. Returns the verified PA rule plus actionable next steps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaLookupResponse" }, "example": { "state": "TX", "program": "medicaid_mco", "query": { "drug_class": "glp1_weight_loss" }, "result": { "pa_required": true, "pa_type": "full", "confidence": 0.9, "notes": "GLP-1 agonists require PA for T2DM (HbA1c >=7.5%, failed metformin). Weight-loss-only indication has very limited coverage in TX Medicaid.", "source_url": "https://www.txvendordrug.com/formulary/prior-authorization", "last_verified": "2026-04-22", "federal_override": false }, "next_steps": [ { "step": 1, "title": "Gather clinical documentation", "items": [ "HbA1c >=7.5%", "failed metformin", "Document prior treatment failure (step therapy required)" ] }, { "step": 2, "title": "Submit PA request", "items": [ "Submit to: Enrollee's MCO plan" ] }, { "step": 3, "title": "Expected turnaround", "items": [ "Standard: 14 days", "Expedited: 72 hours" ] } ], "served_from": "static", "timestamp": "2026-04-23T15:42:01.891Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimit" } } } }, "/v1/states": { "get": { "summary": "State-level PA coverage metadata.", "description": "Without `state` parameter: returns a list of all 51 states with rule counts, PA-required percentage, and policy flags (Medicaid expansion, FFS-dominant, WISER).\n\nWith `state` parameter: returns a detailed breakdown for one state including flags, summary (totals, programs covered, PA-type histogram, federal-protected drug classes, last-verified date), per-service-category PA counts, and per-drug-class PA counts.\n\nNo authentication required. Cached at the edge for 1 hour (`s-maxage=3600`).", "operationId": "states", "tags": [ "Discovery" ], "security": [], "parameters": [ { "name": "state", "in": "query", "required": false, "description": "Optional USPS 2-letter state abbreviation. Omit for the list of all 51 states; supply for a single-state breakdown.", "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "TX" } } ], "responses": { "200": { "description": "State summary. Returns the list form when `state` is omitted, the detail form when `state` is supplied.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StatesListV1Response" }, { "$ref": "#/components/schemas/StateSummaryResponse" } ] } } } }, "400": { "description": "Invalid state code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid state" } } } } } } }, "/v1/topics": { "get": { "summary": "List cross-state pivot topics (drug classes, code families, services, regulations).", "description": "Returns the catalog of approved Auth57 topics — each one is a matcher across the bulletin-event corpus that lets you ask 'what's every state doing on X?'. Use the returned `slug` with `/v1/topics/{slug}` to get the per-state position grid.\n\nTopics are anchored where possible to standard taxonomies (RxNorm VA classes, ATC drug classes) — the `taxonomy_link` field shows the anchor. Match counts reflect the live corpus and grow as more state bulletins are extracted.", "operationId": "listTopics", "tags": [ "Topics" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of approved topics with live match counts.", "content": { "application/json": { "example": { "topics": [ { "slug": "glp1", "display_name": "GLP-1 receptor agonists", "kind": "drug_class", "description": "GLP-1 receptor agonists used for type 2 diabetes and weight management.", "taxonomy_link": "rxnorm:A10BJ", "match_count": 1, "jurisdiction_count": 1 }, { "slug": "biologic-asthma", "display_name": "Biologic asthma therapies", "kind": "drug_class", "description": "Targeted biologics for severe asthma (anti-IgE, anti-IL-5, anti-IL-4Rα, anti-TSLP).", "taxonomy_link": null, "match_count": 2, "jurisdiction_count": 1 }, { "slug": "wiser-model", "display_name": "CMS WISeR Model", "kind": "regulation", "description": "Wasteful and Inappropriate Service Reduction Model — live in 6 states (AZ/NJ/OH/OK/TX/WA) effective Jan 5 2026.", "taxonomy_link": null, "match_count": 0, "jurisdiction_count": 0 } ] } } } }, "401": { "description": "Missing or invalid `x-api-key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/topics/{slug}": { "get": { "summary": "Topic detail: 51-state position grid for a given topic.", "description": "Returns the topic definition plus a per-jurisdiction summary: event count, latest issued/effective/compliance dates, and a status hint (`expanding`, `contracting`, `rule_change`, `rate_change`, `active`, `no_data`). Includes up to 50 sample events with `matched_on` reasons explaining why each event was tagged for this topic.", "operationId": "getTopic", "tags": [ "Topics" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Topic slug (lowercase, hyphens). Use `/v1/topics` to discover slugs.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "example": "glp1" } } ], "responses": { "200": { "description": "Topic detail with per-jurisdiction grid and sample events.", "content": { "application/json": { "example": { "topic": { "slug": "glp1", "display_name": "GLP-1 receptor agonists", "kind": "drug_class", "description": "GLP-1 receptor agonists for type 2 diabetes and weight management.", "taxonomy_link": "rxnorm:A10BJ" }, "by_jurisdiction": { "OK": { "count": 1, "latest_event_at": "2025-04-25", "latest_effective_at": "2025-05-01", "latest_compliance_at": null, "latest_event_kind": "payer_responsibility_clarification", "status_hint": "active" }, "TX": { "count": 0, "latest_event_at": null, "latest_effective_at": null, "latest_compliance_at": null, "latest_event_kind": null, "status_hint": "no_data" } }, "states_with_data": [ "OK" ], "states_without_data": [ "AL", "AK", "AZ", "..." ], "total_matches": 1, "sample_events": [ { "id": 365, "jurisdiction": "OK", "event_kind": "payer_responsibility_clarification", "event_title": "SoonerSelect Service Process Change to Remove GLP1 Medications From Drug Maintenance List", "issued_at": "2025-04-25", "effective_at": "2025-05-01", "mmc_compliance_at": null, "comment_deadline": null, "pa_relevant": true, "source_url": null, "matched_on": [ "term:GLP1" ] } ] } } } }, "400": { "description": "Invalid slug." }, "401": { "description": "Missing or invalid `x-api-key`." }, "404": { "description": "Topic not found or not in `approved` status." } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key as a UUID. Obtain at https://auth57.io/subscribe-api or request demo access via https://auth57.io/book." } }, "parameters": { "State": { "name": "state", "in": "query", "required": true, "description": "USPS 2-letter state abbreviation.", "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "TX" } }, "Program": { "name": "program", "in": "query", "required": true, "description": "Insurance program.", "schema": { "type": "string", "enum": [ "medicaid_mco", "medicaid_ffs", "medicare_advantage", "medicare_traditional", "dual_eligible", "part_d", "chip" ], "example": "medicaid_mco" } }, "Drug": { "name": "drug", "in": "query", "required": false, "description": "`drug_class_code` enum. Provide exactly one of `drug` or `service`. One of 20 canonical drug classes published in the corpus.", "schema": { "type": "string", "enum": [ "adhd_stimulants", "biosimilars", "brand_name_no_generic", "brand_name_with_generic", "compounded_medications", "controlled_schedule_ii", "controlled_schedule_iii_v", "diabetes_insulin", "diabetes_non_insulin", "glp1_weight_loss", "hepatitis_c", "hiv_antiretrovirals", "immunosuppressants", "mental_health_antidepressants", "mental_health_antipsychotics", "oncology_oral", "opioid_treatment", "rare_disease_orphan", "specialty_biologics", "specialty_non_biologic" ], "example": "glp1_weight_loss" } }, "Service": { "name": "service", "in": "query", "required": false, "description": "`service_category` enum. Provide exactly one of `drug` or `service`. One of 20 canonical service categories published in the corpus.", "schema": { "type": "string", "enum": [ "advanced_imaging", "ambulance_transport", "behavioral_health_inpatient", "behavioral_health_outpatient", "dental", "diagnostic_imaging", "durable_medical_equipment", "home_health", "hospice", "inpatient_hospital", "laboratory", "long_term_care", "occupational_therapy", "outpatient_surgery", "pharmacy_standard", "physical_therapy", "skilled_nursing_facility", "specialty_drugs", "speech_therapy", "substance_use_treatment" ], "example": "diagnostic_imaging" } } }, "responses": { "BadRequest": { "description": "Invalid parameters (missing required field, bad format, conflicting drug+service).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid `x-api-key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid API key" } } } }, "Forbidden": { "description": "The requested state, program, or endpoint is not included in your subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "TX not in your subscription" } } } }, "NotFound": { "description": "No verified rule exists for this (state, program, drug_or_service) combination. Consider falling back to the state's provider manual (linked in previous lookups) or contacting the plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Rule not found" } } } }, "RateLimit": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer", "example": 3600 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "example": { "error": "Rate limit exceeded", "limit": 10000, "window": "1 hour", "retry_after_seconds": 3600 } } } } }, "schemas": { "PaRule": { "type": "object", "required": [ "pa_required", "source_url", "last_verified" ], "properties": { "pa_required": { "type": "boolean", "description": "Whether this (state, program, drug_or_service) requires prior authorization." }, "pa_type": { "type": "string", "enum": [ "full", "conditional", "step_therapy", "quantity_limit", "notification_only", "none" ], "description": "When PA is required, the type of authorization needed." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Verification confidence (0–1). Values ≥0.8 are considered high-confidence.", "example": 0.9 }, "notes": { "type": "string", "description": "Plain-language explanation of the rule — criteria, exceptions, common caveats." }, "source_url": { "type": "string", "format": "uri", "description": "Authoritative source the rule was verified against. Cite this URL when quoting the rule." }, "last_verified": { "type": "string", "format": "date", "description": "Date Auth57 last confirmed this rule against the source." }, "federal_override": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "True (or a description string) when a federal mandate overrides the state/plan rule for this entry." } } }, "NextStep": { "type": "object", "required": [ "step", "title", "items" ], "properties": { "step": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Gather clinical documentation" }, "items": { "type": "array", "items": { "type": "string" } } } }, "PaLookupResponse": { "type": "object", "required": [ "state", "program", "query", "result", "next_steps", "served_from", "timestamp" ], "properties": { "state": { "type": "string", "example": "TX" }, "program": { "type": "string", "example": "medicaid_mco" }, "query": { "type": "object", "oneOf": [ { "properties": { "drug_class": { "type": "string" } }, "required": [ "drug_class" ] }, { "properties": { "service_category": { "type": "string" } }, "required": [ "service_category" ] } ] }, "result": { "$ref": "#/components/schemas/PaRule" }, "next_steps": { "type": "array", "items": { "$ref": "#/components/schemas/NextStep" } }, "served_from": { "type": "string", "enum": [ "static", "edge" ], "description": "`static` = served from pre-built edge CDN (fastest). `edge` = served from live Supabase query." }, "timestamp": { "type": "string", "format": "date-time" } } }, "CompareStateResult": { "allOf": [ { "$ref": "#/components/schemas/PaRule" }, { "type": "object", "required": [ "state_abbr" ], "properties": { "state_abbr": { "type": "string", "example": "TX" } } } ] }, "CompareSummary": { "type": "object", "required": [ "total", "require_pa", "no_pa", "divergence", "divergence_summary" ], "properties": { "total": { "type": "integer", "description": "Number of states that returned a rule." }, "require_pa": { "type": "integer" }, "no_pa": { "type": "integer" }, "divergence": { "type": "boolean", "description": "True if the requested states disagree on PA requirement." }, "divergence_summary": { "type": "string", "example": "4 of 5 states require PA. OH is an outlier." } } }, "CompareResponse": { "type": "object", "required": [ "states", "program", "query", "summary", "results", "served_from", "timestamp" ], "properties": { "states": { "type": "array", "items": { "type": "string" } }, "program": { "type": "string" }, "query": { "type": "object" }, "summary": { "$ref": "#/components/schemas/CompareSummary" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CompareStateResult" } }, "served_from": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } }, "StateListItem": { "type": "object", "properties": { "abbr": { "type": "string", "example": "TX" }, "name": { "type": "string", "example": "Texas" }, "total_rules": { "type": "integer", "example": 34 }, "pa_required_pct": { "type": "integer", "nullable": true, "example": 58 }, "non_expansion": { "type": "boolean" }, "ffs_dominant": { "type": "boolean" }, "wiser": { "type": "boolean", "description": "State-specific WISER (work, income, support, enrollment review) flag." } } }, "StatesListResponse": { "type": "object", "properties": { "states": { "type": "array", "items": { "$ref": "#/components/schemas/StateListItem" } } } }, "StateDetailResponse": { "type": "object", "properties": { "state": { "type": "string", "example": "TX" }, "name": { "type": "string", "example": "Texas" }, "flags": { "type": "object", "properties": { "non_expansion": { "type": "boolean" }, "ffs_dominant": { "type": "boolean" }, "wiser": { "type": "boolean" } } }, "summary": { "type": "object", "properties": { "total_rules": { "type": "integer" }, "pa_required_count": { "type": "integer" }, "pa_required_pct": { "type": "integer", "nullable": true }, "programs_covered": { "type": "array", "items": { "type": "string" } }, "pa_type_breakdown": { "type": "object", "additionalProperties": { "type": "integer" } }, "federal_protected_classes_with_pa": { "type": "array", "items": { "type": "string" } }, "last_verified": { "type": "string", "format": "date", "nullable": true } } }, "services": { "type": "object", "additionalProperties": { "type": "object" } }, "drugs": { "type": "object", "additionalProperties": { "type": "object" } } } }, "ManifestResponse": { "type": "object", "required": [ "service", "version", "dataset", "coverage", "mandates", "endpoints", "docs" ], "properties": { "service": { "type": "string", "example": "Auth57", "description": "Stable service identifier." }, "version": { "type": "string", "example": "1", "description": "API major version." }, "dataset": { "type": "object", "required": [ "verified_rules", "service_rules", "drug_rules", "last_verified" ], "properties": { "verified_rules": { "type": "integer", "description": "Total published rules across `pa_rules` and `drug_pa_rules`." }, "service_rules": { "type": "integer", "description": "Published rows in the service-category corpus (`pa_rules`)." }, "drug_rules": { "type": "integer", "description": "Published rows in the drug-class corpus (`drug_pa_rules`)." }, "last_verified": { "type": "string", "format": "date", "nullable": true, "description": "Most recent `last_verified` date across the corpus." } } }, "coverage": { "type": "object", "required": [ "states", "states_count", "programs", "service_categories", "drug_classes" ], "properties": { "states": { "type": "array", "items": { "type": "string" }, "description": "USPS abbreviations of every covered state (51, including DC)." }, "states_count": { "type": "integer", "example": 51 }, "programs": { "type": "array", "items": { "type": "string" }, "description": "Insurance program codes accepted by `program` query parameters." }, "service_categories": { "type": "array", "items": { "type": "string" }, "description": "Canonical service category codes accepted by the `service` query parameter." }, "drug_classes": { "type": "array", "items": { "type": "string" }, "description": "Canonical drug class codes accepted by the `drug` query parameter." } } }, "mandates": { "type": "object", "description": "Federal interoperability mandates the dataset is benchmarked against.", "additionalProperties": { "type": "object", "properties": { "effective": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "final", "proposed" ] } } } }, "endpoints": { "type": "object", "description": "Human-readable map of available endpoints (method + path + parameter sketch).", "additionalProperties": { "type": "string" } }, "docs": { "type": "object", "description": "Pointers to spec, reference UI, and the official SDK.", "properties": { "openapi": { "type": "string", "format": "uri" }, "reference": { "type": "string", "format": "uri" }, "sdk": { "type": "string", "format": "uri" } } } } }, "StateListEntry": { "type": "object", "required": [ "abbr", "name", "total_rules", "pa_required_pct", "non_expansion", "ffs_dominant", "wiser" ], "properties": { "abbr": { "type": "string", "example": "TX", "description": "USPS 2-letter abbreviation." }, "name": { "type": "string", "example": "Texas" }, "total_rules": { "type": "integer", "example": 34, "description": "Count of published rules (services + drugs) for this state." }, "pa_required_pct": { "type": "integer", "example": 58, "description": "Percentage of this state's rules that require PA. Returns 0 when there are no rules yet." }, "non_expansion": { "type": "boolean", "description": "True for the 9 non-Medicaid-expansion states." }, "ffs_dominant": { "type": "boolean", "description": "True for states where fee-for-service Medicaid (not MCO) is the dominant delivery model." }, "wiser": { "type": "boolean", "description": "True for states with WISER (work, income, support, enrollment review) requirements layered onto Medicaid." } } }, "StatesListV1Response": { "type": "object", "required": [ "states" ], "properties": { "states": { "type": "array", "description": "All 51 states (including DC), one entry each.", "items": { "$ref": "#/components/schemas/StateListEntry" } } } }, "StateSummaryFlags": { "type": "object", "required": [ "non_expansion", "ffs_dominant", "wiser" ], "properties": { "non_expansion": { "type": "boolean" }, "ffs_dominant": { "type": "boolean" }, "wiser": { "type": "boolean" } } }, "StateSummaryStats": { "type": "object", "required": [ "total_rules", "pa_required_count", "pa_required_pct", "programs_covered", "pa_type_breakdown", "federal_protected_classes_with_pa", "last_verified" ], "properties": { "total_rules": { "type": "integer", "description": "Total published rules (services + drugs) for this state." }, "pa_required_count": { "type": "integer", "description": "Subset of `total_rules` where `pa_required` is true." }, "pa_required_pct": { "type": "integer", "nullable": true, "description": "Percentage of rules requiring PA. Null when `total_rules` is 0." }, "programs_covered": { "type": "array", "items": { "type": "string" }, "description": "Distinct `program_type` values present in this state's rules." }, "pa_type_breakdown": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Histogram of `pa_type` across rules where PA is required (e.g. `{ \"full\": 12, \"step_therapy\": 4 }`)." }, "federal_protected_classes_with_pa": { "type": "array", "items": { "type": "string" }, "description": "Drug class codes flagged with `federal_override` where the state still requires PA — useful for compliance review." }, "last_verified": { "type": "string", "format": "date", "nullable": true, "description": "Most recent `last_verified` across this state's rules." } } }, "StateServiceBreakdown": { "type": "object", "required": [ "required", "total" ], "properties": { "required": { "type": "integer", "description": "Number of program/service rows in this category that require PA." }, "total": { "type": "integer", "description": "Total program/service rows in this category." } } }, "StateDrugBreakdown": { "type": "object", "required": [ "required", "total" ], "properties": { "required": { "type": "integer", "description": "Number of program/drug rows in this class that require PA." }, "total": { "type": "integer", "description": "Total program/drug rows in this class." }, "federal_override": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "True (or descriptive string) if a federal mandate overrides state rules for this drug class." } } }, "StateSummaryResponse": { "type": "object", "required": [ "state", "name", "flags", "summary", "services", "drugs" ], "properties": { "state": { "type": "string", "example": "TX" }, "name": { "type": "string", "example": "Texas" }, "flags": { "$ref": "#/components/schemas/StateSummaryFlags" }, "summary": { "$ref": "#/components/schemas/StateSummaryStats" }, "services": { "type": "object", "description": "Per-service-category PA breakdown. Keys are `service_category` codes.", "additionalProperties": { "$ref": "#/components/schemas/StateServiceBreakdown" } }, "drugs": { "type": "object", "description": "Per-drug-class PA breakdown. Keys are `drug_class_code` values.", "additionalProperties": { "$ref": "#/components/schemas/StateDrugBreakdown" } } } }, "LookupOption": { "type": "object", "required": [ "val", "label" ], "properties": { "val": { "type": "string", "description": "Canonical code (e.g. `glp1_weight_loss`, `inpatient_hospital`). Pass this back to `/v1/pa-lookup` as `drug` or `service`." }, "label": { "type": "string", "description": "Human-readable label suitable for a dropdown option." } } }, "LookupOptionsResponse": { "type": "object", "required": [ "drugs", "services" ], "properties": { "drugs": { "type": "array", "items": { "$ref": "#/components/schemas/LookupOption" }, "description": "Drug classes with published rules for this (state, program). Empty when none exist." }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/LookupOption" }, "description": "Service categories with published rules for this (state, program). Empty when none exist." } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "signup_url": { "type": "string", "format": "uri" } } }, "RateLimitError": { "type": "object", "required": [ "error", "limit", "window", "retry_after_seconds" ], "properties": { "error": { "type": "string", "example": "Rate limit exceeded" }, "limit": { "type": "integer", "example": 10000 }, "window": { "type": "string", "example": "1 hour" }, "retry_after_seconds": { "type": "integer", "example": 3600 } } } } } }