{
  "openapi": "3.1.0",
  "info": {
    "title": "Seekapedia Liquor License API",
    "version": "1.0.0",
    "description": "State alcohol license records (Texas, New York, California, Colorado, Oregon, Georgia, Washington, Virginia, Michigan, Missouri, Nebraska, Indiana, Florida) from official agency publications, with freshness and reconciliation on every answer, saved checks, policies, portfolios, change webhooks, reviews and an audit log. Information to check, not legal advice or a finding of compliance. Enforcement actions and license conditions are not covered.",
    "contact": {
      "name": "Seekapedia",
      "email": "support@kixlogic.com"
    }
  },
  "servers": [
    {
      "url": "https://api.seekapedia.com"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "tags": [
    {
      "name": "Lookup"
    },
    {
      "name": "Checks and policies"
    },
    {
      "name": "Monitoring"
    },
    {
      "name": "History"
    },
    {
      "name": "Governance"
    },
    {
      "name": "Account"
    },
    {
      "name": "Service"
    }
  ],
  "paths": {
    "/v1/health": {
      "get": {
        "tags": [
          "Service"
        ],
        "summary": "Service status, data_as_of and record counts per state. No key needed.",
        "security": [],
        "responses": {
          "200": {
            "description": "Health",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data_as_of": {
                      "type": "string"
                    },
                    "records_by_state": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/sources": {
      "get": {
        "tags": [
          "Service"
        ],
        "summary": "Each agency dataset, its schedule, and whether our fetch and the agency publication are current. No key needed.",
        "security": [],
        "responses": {
          "200": {
            "description": "Sources",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sources": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/releases": {
      "get": {
        "tags": [
          "Service"
        ],
        "summary": "The release log: every daily sync with its totals, per-state outcome and what changed (added, status_changed, expiration_changed, missing_from_source, reappeared, conflict_detected). No key needed.",
        "security": [],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 60
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Releases",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "releases": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "data_as_of": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/openapi.json": {
      "get": {
        "tags": [
          "Service"
        ],
        "summary": "This document. No key needed.",
        "security": [],
        "responses": {
          "200": {
            "description": "OpenAPI document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/verify": {
      "get": {
        "summary": "Look up one license by state and number.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Lookup"
        ],
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "description": "Two-letter state code: TX, NY, CA, CO or OR.",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            }
          },
          {
            "name": "license_number",
            "in": "query",
            "description": "The agency license number (California: file number or file-type).",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "policy",
            "in": "query",
            "description": "A saved policy id to apply to the result.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "policy_version",
            "in": "query",
            "description": "A specific policy version (default: the latest).",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Makes a retry free and returns the first result.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The record with freshness, reconciliation and data_result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LicenseResult"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          },
          "404": {
            "description": "Not found in the covered sources"
          },
          "429": {
            "description": "Monthly quota reached"
          }
        }
      }
    },
    "/v1/verify/batch": {
      "post": {
        "summary": "Look up up to 500 licenses in one request.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Lookup"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "state": {
                          "type": "string"
                        },
                        "license_number": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "policy": {
                    "type": "string"
                  }
                },
                "required": [
                  "items"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Makes a retry free and returns the first result.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One result per item",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/search": {
      "get": {
        "summary": "Search by name (contains match), optionally within a state.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Lookup"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "description": "Part of a legal or trade name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "description": "Two-letter state code: TX, NY, CA, CO or OR.",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            }
          },
          {
            "name": "record_kind",
            "in": "query",
            "description": "license (default), application or all",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The next_cursor from the previous page. Cursors are signed, expire after 24 hours and are bound to the filters and key that issued them.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of matching records",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/history": {
      "get": {
        "summary": "Recorded changes to one license, newest first.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "History"
        ],
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "description": "Two-letter state code: TX, NY, CA, CO or OR.",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            }
          },
          {
            "name": "license_number",
            "in": "query",
            "description": "The agency license number (California: file number or file-type).",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Change history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/changes": {
      "get": {
        "summary": "The change feed for the latest sync, or everything since a time.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Monitoring"
        ],
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "description": "Two-letter state code: TX, NY, CA, CO or OR.",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            }
          },
          {
            "name": "since",
            "in": "query",
            "description": "ISO date or time",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The next_cursor from the previous page. Cursors are signed, expire after 24 hours and are bound to the filters and key that issued them.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of changes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/as-of": {
      "get": {
        "summary": "A license as our data stood at an earlier time, optionally judged by a policy version.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "History"
        ],
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "description": "Two-letter state code: TX, NY, CA, CO or OR.",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            }
          },
          {
            "name": "license_number",
            "in": "query",
            "description": "The agency license number (California: file number or file-type).",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "license_id",
            "in": "query",
            "description": "Alternative to state and license_number",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "as_of",
            "in": "query",
            "description": "An ISO date or time: judge the data as it stood then (history starts 2026-11-19).",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "policy",
            "in": "query",
            "description": "A saved policy id to apply to the result.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "policy_version",
            "in": "query",
            "description": "A specific policy version (default: the latest).",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "policy_in_force",
            "in": "query",
            "description": "true: use the policy version saved most recently before as_of",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The reconstructed record and result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "as_of is before our history, in the future, or malformed"
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/checks": {
      "post": {
        "summary": "Run and save a standard check (identifier or name and address).",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Checks and policies"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Makes a retry free and returns the first result.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "state": {
                    "type": "string"
                  },
                  "license_number": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "address": {
                    "type": "string"
                  },
                  "zip": {
                    "type": "string"
                  },
                  "reference": {
                    "type": "string"
                  },
                  "policy": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The saved check",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Check"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          },
          "429": {
            "description": "Monthly quota reached"
          }
        }
      },
      "get": {
        "summary": "List saved checks.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Checks and policies"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The next_cursor from the previous page. Cursors are signed, expire after 24 hours and are bound to the filters and key that issued them.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of checks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/checks/batch": {
      "post": {
        "summary": "Up to 50 checks in one request.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Checks and policies"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Makes a retry free and returns the first result.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": true
                    }
                  },
                  "policy": {
                    "type": "string"
                  }
                },
                "required": [
                  "items"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/checks/{id}": {
      "get": {
        "summary": "One saved check.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Checks and policies"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Check id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The check",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Check"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      },
      "delete": {
        "summary": "Delete a saved check.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Checks and policies"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Check id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/checks/{id}/reevaluate": {
      "post": {
        "summary": "Re-judge a saved check under another policy or version, using the data saved with it.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "History"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Check id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "policy": {
                    "type": "string"
                  },
                  "policy_version": {
                    "type": "integer"
                  },
                  "policy_in_force_at_time": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "policy"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Original and new outcome",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/policies": {
      "post": {
        "summary": "Save a policy (a new immutable version each time).",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Checks and policies"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "policy_id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "rules": {
                    "type": "object",
                    "properties": {},
                    "additionalProperties": true
                  }
                },
                "required": [
                  "policy_id",
                  "rules"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      },
      "get": {
        "summary": "List policies.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Checks and policies"
        ],
        "responses": {
          "200": {
            "description": "Policies",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/portfolios": {
      "post": {
        "summary": "Create a portfolio.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Monitoring"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      },
      "get": {
        "summary": "List portfolios.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Monitoring"
        ],
        "responses": {
          "200": {
            "description": "Portfolios",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/portfolios/{id}/items": {
      "post": {
        "summary": "Add up to 500 licenses; with webhook_url, also watch them.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Monitoring"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Portfolio id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "state": {
                          "type": "string"
                        },
                        "license_number": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "webhook_url": {
                    "type": "string"
                  }
                },
                "required": [
                  "items"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/portfolios/{id}/status": {
      "get": {
        "summary": "Every license in the portfolio, optionally judged by a policy and/or as of a past time.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Monitoring"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Portfolio id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "policy",
            "in": "query",
            "description": "A saved policy id to apply to the result.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "policy_version",
            "in": "query",
            "description": "A specific policy version (default: the latest).",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "as_of",
            "in": "query",
            "description": "An ISO date or time: judge the data as it stood then (history starts 2026-11-19).",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The next_cursor from the previous page. Cursors are signed, expire after 24 hours and are bound to the filters and key that issued them.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/portfolios/{id}/exceptions": {
      "get": {
        "summary": "Only the licenses that need a person, with reasons.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Monitoring"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Portfolio id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "policy",
            "in": "query",
            "description": "A saved policy id to apply to the result.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "policy_version",
            "in": "query",
            "description": "A specific policy version (default: the latest).",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "as_of",
            "in": "query",
            "description": "An ISO date or time: judge the data as it stood then (history starts 2026-11-19).",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The next_cursor from the previous page. Cursors are signed, expire after 24 hours and are bound to the filters and key that issued them.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of exceptions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/watches": {
      "post": {
        "summary": "Watch licenses; a signed webhook fires when one changes.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Monitoring"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": true
                    }
                  },
                  "webhook_url": {
                    "type": "string"
                  }
                },
                "required": [
                  "items",
                  "webhook_url"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created; each secret is shown once"
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      },
      "get": {
        "summary": "List watches.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Monitoring"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The next_cursor from the previous page. Cursors are signed, expire after 24 hours and are bound to the filters and key that issued them.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Watches",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/deliveries": {
      "get": {
        "summary": "Webhook delivery history.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Monitoring"
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "description": "pending, delivered or failed",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The next_cursor from the previous page. Cursors are signed, expire after 24 hours and are bound to the filters and key that issued them.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deliveries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/export": {
      "get": {
        "summary": "Bulk export of records, paged from one consistent snapshot.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Lookup"
        ],
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "description": "Two-letter state code: TX, NY, CA, CO or OR.",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            }
          },
          {
            "name": "record_kind",
            "in": "query",
            "description": "license, application or all",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Normalized status",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "description": "csv for a spreadsheet-ready download (header on the first page only; cursor in the x-next-cursor header; cells starting with = + - @ are prefixed with an apostrophe)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The next_cursor from the previous page. Cursors are signed, expire after 24 hours and are bound to the filters and key that issued them.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of records",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          },
          "409": {
            "description": "snapshot_expired: a sync landed mid-export; restart"
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "summary": "This month's billing units, your plan and limits, and monitored locations.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Account"
        ],
        "parameters": [
          {
            "name": "period",
            "in": "query",
            "description": "YYYY-MM",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Usage and plan",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/members": {
      "post": {
        "summary": "Issue a team key with a role (viewer, reviewer, approver, admin).",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "role": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "role"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created; the key is shown once"
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      },
      "get": {
        "summary": "List team members.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "responses": {
          "200": {
            "description": "Members",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/reviews": {
      "post": {
        "summary": "Open a review for a license.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "license_id": {
                    "type": "string"
                  },
                  "assignee": {
                    "type": "string"
                  },
                  "due_at": {
                    "type": "string"
                  },
                  "portfolio_id": {
                    "type": "string"
                  },
                  "note": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      },
      "get": {
        "summary": "List reviews.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "description": "open, in_review, escalated, pending_approval, approved",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assignee",
            "in": "query",
            "description": "Member id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "overdue",
            "in": "query",
            "description": "true: open reviews past due_at",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The next_cursor from the previous page. Cursors are signed, expire after 24 hours and are bound to the filters and key that issued them.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Reviews",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/reviews/{id}": {
      "get": {
        "summary": "A review with its events.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Review id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The review",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/reviews/{id}/package": {
      "get": {
        "summary": "Decision package: data when opened, data now, every step.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Review id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The package",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/audit": {
      "get": {
        "summary": "The account audit log (approver or admin).",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "parameters": [
          {
            "name": "review_id",
            "in": "query",
            "description": "Filter",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "action",
            "in": "query",
            "description": "Filter",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The next_cursor from the previous page. Cursors are signed, expire after 24 hours and are bound to the filters and key that issued them.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of entries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/audit/verify": {
      "get": {
        "summary": "Checks the audit hash chain.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "responses": {
          "200": {
            "description": "valid, entries_checked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/audit/export": {
      "get": {
        "summary": "Audit export; format=ndjson for a download.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "description": "ndjson or omit for JSON",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The next_cursor from the previous page. Cursors are signed, expire after 24 hours and are bound to the filters and key that issued them.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/alerts": {
      "post": {
        "summary": "Subscribe an email address to alerts (it must confirm first).",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Account"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "email",
                  "events"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created, unconfirmed"
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      },
      "get": {
        "summary": "List alert subscriptions.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Account"
        ],
        "responses": {
          "200": {
            "description": "Subscriptions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/webhooks": {
      "post": {
        "summary": "Register a signed webhook for review events (admin). The secret is shown once.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "url",
                  "events"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created, with the signing secret"
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      },
      "get": {
        "summary": "List webhooks and their last delivery result.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "responses": {
          "200": {
            "description": "Webhooks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/webhooks/{id}": {
      "delete": {
        "summary": "Delete a webhook.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Webhook id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/webhooks/{id}/test": {
      "post": {
        "summary": "Send a synthetic signed event to one webhook.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Webhook id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Delivery result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/sso": {
      "put": {
        "summary": "Configure OpenID Connect single sign-on.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "issuer": {
                    "type": "string"
                  },
                  "client_id": {
                    "type": "string"
                  },
                  "client_secret": {
                    "type": "string"
                  },
                  "allowed_domains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "default_role": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Configured",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      },
      "get": {
        "summary": "Read the SSO configuration.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "responses": {
          "200": {
            "description": "Configuration",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/saml": {
      "put": {
        "summary": "Configure SAML 2.0 single sign-on.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "idp_sso_url": {
                    "type": "string"
                  },
                  "idp_issuer": {
                    "type": "string"
                  },
                  "idp_certificate": {
                    "type": "string"
                  },
                  "allowed_domains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Configured",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      },
      "get": {
        "summary": "Read the SAML configuration.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "responses": {
          "200": {
            "description": "Configuration",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    },
    "/v1/scim": {
      "put": {
        "summary": "Enable SCIM 2.0 provisioning; returns the token once.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "default_role": {
                    "type": "string"
                  },
                  "group_roles": {
                    "type": "object",
                    "properties": {},
                    "additionalProperties": true
                  },
                  "rotate_token": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Enabled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      },
      "get": {
        "summary": "Read the SCIM configuration.",
        "security": [
          {
            "bearer": []
          }
        ],
        "tags": [
          "Governance"
        ],
        "responses": {
          "200": {
            "description": "Configuration",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your API key, or a team or sign-in key, sent as Authorization: Bearer <key>."
      }
    },
    "schemas": {
      "LicenseResult": {
        "type": "object",
        "properties": {
          "found": {
            "type": "boolean"
          },
          "id": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "license_number": {
            "type": "string"
          },
          "license_type": {
            "type": "string"
          },
          "legal_name": {
            "type": "string"
          },
          "trade_name": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "zip": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "Normalized: active, expired, suspended, cancelled, surrendered, pending, revocation_pending, inactive, unknown"
          },
          "status_raw": {
            "type": "string",
            "description": "The agency text, unchanged (derived for New York, Colorado and Oregon, which publish no status text)"
          },
          "expiration_date": {
            "type": "string"
          },
          "expiration_passed": {
            "type": "boolean"
          },
          "freshness": {
            "type": "object",
            "properties": {
              "state": {
                "type": "string"
              },
              "ingestion": {
                "type": "string"
              },
              "publication": {
                "type": "string"
              }
            },
            "additionalProperties": true
          },
          "reconciliation": {
            "type": "object",
            "properties": {
              "state": {
                "type": "string"
              },
              "conflicting_fields": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "additionalProperties": true
          },
          "data_result": {
            "type": "object",
            "properties": {
              "found": {
                "type": "boolean"
              },
              "normalized_status": {
                "type": "string"
              },
              "freshness_state": {
                "type": "string"
              },
              "reconciliation_state": {
                "type": "string"
              },
              "enforcement_review_state": {
                "type": "string",
                "const": "not_covered"
              }
            },
            "additionalProperties": true
          },
          "customer_policy_result": {
            "type": "object",
            "properties": {
              "policy_id": {
                "type": "string"
              },
              "version": {
                "type": "integer"
              },
              "outcome": {
                "type": "string",
                "enum": [
                  "meets_policy",
                  "review_required",
                  "does_not_meet_policy"
                ]
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "Check": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "match_outcome": {
            "type": "string"
          },
          "data_result": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          },
          "customer_policy_result": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": true
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": true
      }
    }
  }
}