{
  "openapi": "3.1.0",
  "info": {
    "title": "Seekapedia Cannabis License API",
    "version": "1.0.0",
    "description": "State cannabis license records (Oregon, New York, Connecticut) 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. Cannabis is regulated differently in each state: a license here is a state license only, and federal law still treats cannabis as a controlled substance.",
    "contact": {
      "name": "Seekapedia",
      "email": "support@kixlogic.com"
    }
  },
  "servers": [
    {
      "url": "https://cannabis-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
      }
    }
  }
}