{
  "openapi": "3.1.0",
  "info": {
    "title": "Florida Business API",
    "version": "1.0.0",
    "description": "Commercial REST API for Florida Division of Corporations records. Independent commercial service. Not affiliated with Sunbiz.org, the Florida Department of State, or the Florida Division of Corporations."
  },
  "servers": [
    {
      "url": "https://api.floridabusinessapi.com/v1",
      "description": "Production API"
    },
    {
      "url": "https://floridabusinessapi.com/api/v1",
      "description": "Same-origin API proxy"
    },
    {
      "url": "http://localhost:3000/api/v1",
      "description": "Local dev"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "AccountUsageBody": {
        "type": "object",
        "properties": {
          "events_count": {
            "type": "integer"
          },
          "monthly_quota": {
            "type": "integer"
          },
          "percent_used": {
            "type": "number"
          },
          "reset_date": {
            "type": "string",
            "description": "ISO-8601 UTC timestamp of next month start"
          },
          "plan": {
            "type": "string"
          }
        },
        "required": [
          "events_count",
          "monthly_quota",
          "percent_used",
          "reset_date",
          "plan"
        ]
      },
      "AccountUsageResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/AccountUsageBody"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "AddressHit": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "zip": {
            "type": "string"
          },
          "document_number": {
            "type": "string"
          },
          "entity_name": {
            "type": "string"
          }
        },
        "required": [
          "address",
          "city",
          "state",
          "zip",
          "document_number",
          "entity_name"
        ]
      },
      "AddressSearchInput": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "default": 25
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "default": 0
          }
        },
        "required": [
          "limit",
          "offset"
        ],
        "description": "Query parameters for GET /api/v1/addresses/search"
      },
      "AddressSearchResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AddressHit"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "pagination",
          "meta"
        ]
      },
      "AgentHit": {
        "type": "object",
        "properties": {
          "agent_name": {
            "type": "string"
          },
          "linked_entity_count": {
            "type": "integer"
          },
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "zip": {
            "type": "string"
          }
        },
        "required": [
          "agent_name",
          "linked_entity_count",
          "city",
          "state",
          "zip"
        ]
      },
      "AgentSearchInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "default": 25
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "default": 0
          }
        },
        "required": [
          "limit",
          "offset"
        ],
        "description": "Query parameters for GET /api/v1/agents/search"
      },
      "AgentSearchResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentHit"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/paginationMetaSchema"
          },
          "meta": {
            "$ref": "#/components/schemas/responseMetaSchema"
          }
        },
        "required": [
          "data",
          "pagination",
          "meta"
        ]
      },
      "DailyFilingsInput": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "default": 25
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "default": 0
          }
        },
        "required": [
          "limit",
          "offset"
        ],
        "description": "Query parameters for GET /api/v1/filings/daily"
      },
      "DailyFilingsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FilingHit"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "pagination",
          "meta"
        ]
      },
      "EntityDetail": {
        "type": "object",
        "properties": {
          "document_number": {
            "type": "string"
          },
          "entity_name": {
            "type": "string"
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "entity_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "filing_date": {
            "type": [
              "string",
              "null"
            ]
          },
          "principal_address": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "line1": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "state": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "postal_code": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "line1",
              "city",
              "state",
              "postal_code"
            ]
          },
          "mailing_address": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "line1": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "state": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "postal_code": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "line1",
              "city",
              "state",
              "postal_code"
            ]
          },
          "registered_agent": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "address": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "line1": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "city": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "state": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "postal_code": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "line1",
                  "city",
                  "state",
                  "postal_code"
                ]
              }
            },
            "required": [
              "name",
              "address"
            ]
          },
          "officers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "title": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "name",
                "title"
              ]
            }
          },
          "recent_filings": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "event_type": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "event_date": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "document_number": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "event_type",
                "event_date",
                "document_number",
                "description"
              ]
            }
          }
        },
        "required": [
          "document_number",
          "entity_name",
          "status",
          "entity_type",
          "filing_date",
          "principal_address",
          "mailing_address",
          "registered_agent",
          "officers",
          "recent_filings"
        ]
      },
      "EntityDetailInput": {
        "type": "object",
        "properties": {
          "document_number": {
            "type": "string",
            "pattern": "^[A-Za-z0-9]{6,12}$"
          }
        },
        "required": [
          "document_number"
        ],
        "description": "Path parameter for GET /api/v1/entities/{document_number}"
      },
      "EntityHit": {
        "type": "object",
        "properties": {
          "document_number": {
            "type": "string"
          },
          "entity_name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "filing_date": {
            "type": "string"
          },
          "principal_city": {
            "type": "string"
          },
          "principal_state": {
            "type": "string"
          },
          "principal_zip": {
            "type": "string"
          }
        },
        "required": [
          "document_number",
          "entity_name",
          "status",
          "entity_type",
          "filing_date",
          "principal_city",
          "principal_state",
          "principal_zip"
        ]
      },
      "EntitySearchInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ]
          },
          "entity_type": {
            "type": "string",
            "maxLength": 20
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "default": 25
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "default": 0
          }
        },
        "required": [
          "limit",
          "offset"
        ],
        "description": "Query parameters for GET /api/v1/entities/search"
      },
      "EntitySearchResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EntityHit"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "pagination",
          "meta"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string",
                "description": "Human-readable error message."
              },
              "request_id": {
                "type": "string",
                "description": "Correlation id; surface this when filing support tickets."
              },
              "details": {
                "type": "object",
                "additionalProperties": {},
                "propertyNames": {
                  "type": "string"
                },
                "description": "Optional structured details, e.g. Zod issues on a 400."
              }
            },
            "required": [
              "code",
              "message",
              "request_id"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "FilingHit": {
        "type": "object",
        "properties": {
          "document_number": {
            "type": "string"
          },
          "entity_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "filing_type": {
            "type": "string"
          },
          "filing_date": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "required": [
          "document_number",
          "entity_name",
          "entity_type",
          "filing_type",
          "filing_date",
          "status"
        ]
      },
      "LeadHit": {
        "type": "object",
        "properties": {
          "document_number": {
            "type": "string"
          },
          "entity_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "filing_date": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "zip": {
            "type": "string"
          },
          "county": {
            "type": "string"
          }
        },
        "required": [
          "document_number",
          "entity_name",
          "entity_type",
          "filing_date",
          "city",
          "state",
          "zip",
          "county"
        ]
      },
      "LeadsInput": {
        "type": "object",
        "properties": {
          "county": {
            "type": "string",
            "maxLength": 40
          },
          "city": {
            "type": "string",
            "maxLength": 60
          },
          "entity_type": {
            "type": "string",
            "maxLength": 20
          },
          "date_from": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "date_to": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "default": 25
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "default": 0
          }
        },
        "required": [
          "limit",
          "offset"
        ],
        "description": "Query parameters for GET /api/v1/leads/new-businesses"
      },
      "LeadsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LeadHit"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "pagination",
          "meta"
        ]
      },
      "OfficerHit": {
        "type": "object",
        "properties": {
          "officer_name": {
            "type": "string"
          },
          "title_code": {
            "type": "string"
          },
          "document_number": {
            "type": "string"
          },
          "entity_name": {
            "type": "string"
          }
        },
        "required": [
          "officer_name",
          "title_code",
          "document_number",
          "entity_name"
        ]
      },
      "OfficerSearchInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "title": {
            "type": "string",
            "maxLength": 20
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "default": 25
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "default": 0
          }
        },
        "required": [
          "limit",
          "offset"
        ],
        "description": "Query parameters for GET /api/v1/officers/search"
      },
      "OfficerSearchResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OfficerHit"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "pagination",
          "meta"
        ]
      },
      "PaginationMeta": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "has_more": {
            "type": "boolean"
          }
        },
        "required": [
          "limit",
          "offset",
          "total",
          "has_more"
        ]
      },
      "RecentFilingsInput": {
        "type": "object",
        "properties": {
          "days": {
            "type": "integer",
            "minimum": 1,
            "maximum": 90,
            "default": 7
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "default": 25
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "default": 0
          }
        },
        "required": [
          "days",
          "limit",
          "offset"
        ],
        "description": "Query parameters for GET /api/v1/filings/recent"
      },
      "RecentFilingsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FilingHit"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "pagination",
          "meta"
        ]
      },
      "ResponseMeta": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "request_id"
        ]
      }
    },
    "responses": {}
  },
  "paths": {
    "/account/usage": {
      "get": {
        "operationId": "get-account-usage",
        "summary": "Current monthly usage",
        "description": "Current API key's monthly usage — events_count, monthly_quota,",
        "tags": [
          "Account"
        ],
        "parameters": [],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current month usage envelope with monthly quota, percent used, plan tier, and the UTC reset date.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountUsageResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid X-API-Key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/addresses/search": {
      "get": {
        "operationId": "get-addresses-search",
        "summary": "Search addresses",
        "description": "Search Florida business addresses by street, city, or ZIP. Returns matching addresses and linked entities.",
        "tags": [
          "Addresses"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 25
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "List envelope of AddressHit rows with pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddressSearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid X-API-Key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or monthly quota exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/search": {
      "get": {
        "operationId": "get-agents-search",
        "summary": "Search registered agents",
        "description": "Search Florida registered agents by name (fuzzy). Returns agent name, linked entity count, and agent filing address.",
        "tags": [
          "Agents"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "name",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 25
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "List envelope of AgentHit rows with pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentSearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid X-API-Key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or monthly quota exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/entities/{document_number}": {
      "get": {
        "operationId": "get-entities-{document_number}",
        "summary": "Get entity by document number",
        "description": "Full detail for a single Florida business entity by document number. Includes principal/mailing addresses, registered agent, officers (no PII addresses), and the 50 most-recent filing events.",
        "tags": [
          "Entities"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "document_number",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9]{6,12}$"
            },
            "example": "example"
          }
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Full entity record with addresses, registered agent, officers, and recent filings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityDetail"
                }
              }
            }
          },
          "400": {
            "description": "Invalid document_number format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid X-API-Key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Entity not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or monthly quota exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/entities/search": {
      "get": {
        "operationId": "get-entities-search",
        "summary": "Search entities",
        "description": "Search Florida business entities by name (fuzzy), status, or type. Results ranked by exact match -> prefix -> trigram similarity -> recent filings.",
        "tags": [
          "Entities"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "name",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "inactive"
              ]
            }
          },
          {
            "in": "query",
            "name": "entity_type",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 20
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 25
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "List envelope of EntityHit rows with pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntitySearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid X-API-Key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or monthly quota exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/filings/daily": {
      "get": {
        "operationId": "get-filings-daily",
        "summary": "Daily filings by date",
        "description": "Entities filed on a specific date (Sunbiz daily file).",
        "tags": [
          "Filings"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "date",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 25
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "List envelope of FilingHit rows for the given date with pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DailyFilingsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters (e.g. malformed date).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid X-API-Key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or monthly quota exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/filings/recent": {
      "get": {
        "operationId": "get-filings-recent",
        "summary": "Recent filings by window",
        "description": "Entities filed in the last N days (capped at 90 days).",
        "tags": [
          "Filings"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "days",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 90,
              "default": 7
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 25
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "List envelope of FilingHit rows from the last N days with pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecentFilingsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters (days out of range).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid X-API-Key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or monthly quota exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/leads/new-businesses": {
      "get": {
        "operationId": "get-leads-new-businesses",
        "summary": "New-business lead feed",
        "description": "Filtered new-business lead feed (Lead Feed tier deliverable). Filter by county (FL only), city, entity_type, and filing date range.",
        "tags": [
          "Leads"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "county",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "in": "query",
            "name": "city",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          },
          {
            "in": "query",
            "name": "entity_type",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 20
            }
          },
          {
            "in": "query",
            "name": "date_from",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            }
          },
          {
            "in": "query",
            "name": "date_to",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 25
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "List envelope of LeadHit rows with pagination. Lead Feed tier required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeadsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid X-API-Key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Plan tier does not include the new-business lead feed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or monthly quota exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/officers/search": {
      "get": {
        "operationId": "get-officers-search",
        "summary": "Search officers",
        "description": "Search Florida business officers by name (fuzzy) and title with cross-entity matching. Returns officer name + title + linked entity. Does NOT return officer addresses (PII).",
        "tags": [
          "Officers"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "name",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          {
            "in": "query",
            "name": "title",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 20
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 25
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "List envelope of OfficerHit rows with pagination. Officer addresses are intentionally NOT returned (PII gate).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OfficerSearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid X-API-Key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or monthly quota exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Account"
    },
    {
      "name": "Addresses"
    },
    {
      "name": "Agents"
    },
    {
      "name": "Entities"
    },
    {
      "name": "Filings"
    },
    {
      "name": "Leads"
    },
    {
      "name": "Officers"
    }
  ]
}