{
  "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, 6 programs, 14 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/pa-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." }
  ],
  "paths": {
    "/v1/pa-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.",
        "operationId": "paLookup",
        "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/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" }
        }
      }
    },
    "/api/states-summary": {
      "get": {
        "summary": "State-level PA coverage metadata.",
        "description": "Without `state` parameter: returns a summary array of all 51 states with total_rules, pa_required_pct, and policy flags (Medicaid expansion, FFS-dominant, WISER).\n\nWith `state` parameter: returns a detailed breakdown for one state including program coverage, PA type histogram, federal-protected drug classes, and last-verified date.\n\nCached at the edge for 1 hour.",
        "operationId": "statesSummary",
        "tags": ["Metadata"],
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Optional USPS 2-letter state abbreviation. Omit for a summary of all 51 states.",
            "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "TX" }
          }
        ],
        "responses": {
          "200": {
            "description": "State summary (list or detail).",
            "content": {
              "application/json": {
                "schema": { "oneOf": [
                  { "$ref": "#/components/schemas/StatesListResponse" },
                  { "$ref": "#/components/schemas/StateDetailResponse" }
                ]}
              }
            }
          },
          "400": {
            "description": "Invalid state code.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    }
  },
  "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: `glp1_weight_loss`, `diabetes_insulin`, `diabetes_non_insulin`, `specialty_biologics`, `biosimilars`, `immunosuppressants`, `hiv_antiretrovirals`, `mental_health_antidepressants`, `mental_health_antipsychotics`, `oncology_oral`, `opioid_treatment`, `hepatitis_c`, `adhd_stimulants`, `rare_disease_orphan`, `controlled_schedule_ii`, `controlled_schedule_iii_v`, `brand_name_no_generic`, `brand_name_with_generic`, `compounded_medications`, `specialty_non_biologic`.",
        "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,63}$", "example": "glp1_weight_loss" }
      },
      "Service": {
        "name": "service",
        "in": "query",
        "required": false,
        "description": "`service_category` enum. Provide exactly one of `drug` or `service`. 14 canonical categories: `inpatient_hospital`, `outpatient_surgery`, `diagnostic_imaging`, `home_health`, `durable_medical_equipment`, `mental_health_inpatient`, `occupational_therapy`, `physical_therapy`, `skilled_nursing_facility`, `specialty_drugs`, `speech_therapy`, `substance_use_treatment`, `laboratory`, `ambulance_transport`. (Ohio uses an extended taxonomy.)",
        "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,63}$", "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" } }
        }
      },
      "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 }
        }
      }
    }
  }
}