{
  "openapi": "3.1.0",
  "info": {
    "title": "Florida Tax Certificate API",
    "version": "1.0.0",
    "description": "Commercial REST API for Florida statewide tax-certificate, certificate-sale, certificate-holder, and lands-available records (delinquent-tax / tax-lien data) across all 67 counties. Independent commercial service. Not affiliated with the Florida Department of Revenue, any county property appraiser or tax collector, LienHub, RealAuction, TaxCertSale, or any government agency."
  },
  "servers": [
    {
      "url": "https://fltaxcerts.com/api/v1",
      "description": "Production API"
    }
  ],
  "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"
        ]
      },
      "CertificateCounts": {},
      "CertificateFieldDescriptor": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Canonical tax_certificates column name."
          },
          "label": {
            "type": "string",
            "description": "Human-readable label."
          },
          "category": {
            "type": "string",
            "enum": [
              "identification",
              "owner",
              "location",
              "amounts",
              "sale",
              "status",
              "legal",
              "source",
              "attributes",
              "other"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "string",
              "number",
              "integer",
              "date",
              "boolean",
              "object"
            ]
          }
        },
        "required": [
          "code",
          "label",
          "category",
          "type"
        ]
      },
      "CertificateFieldDictionary": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/CertificateFieldDescriptor"
        }
      },
      "CertificateFreshness": {
        "type": "object",
        "properties": {
          "total": {
            "type": "number"
          },
          "latest_tax_year": {
            "type": [
              "number",
              "null"
            ]
          },
          "last_ingested_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_source_success_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "total",
          "latest_tax_year",
          "last_ingested_at",
          "last_source_success_at"
        ]
      },
      "CertificateHit": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "certificate_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "county_slug": {
            "type": "string"
          },
          "parcel_id": {
            "type": "string"
          },
          "parcel_ref": {
            "type": [
              "string",
              "null"
            ]
          },
          "tax_year": {
            "type": [
              "integer",
              "null"
            ]
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "face_amount": {
            "type": [
              "number",
              "null"
            ]
          },
          "delinquent_amount": {
            "type": [
              "number",
              "null"
            ]
          },
          "total_due": {
            "type": [
              "number",
              "null"
            ]
          },
          "interest_rate": {
            "type": [
              "number",
              "null"
            ]
          },
          "bid_rate": {
            "type": [
              "number",
              "null"
            ]
          },
          "sale_date": {
            "type": [
              "string",
              "null"
            ]
          },
          "batch_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "holder_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "redeemed_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "owner_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "site_address_full": {
            "type": [
              "string",
              "null"
            ]
          },
          "legal_description": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_vendor": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_url": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "certificate_number",
          "county_slug",
          "parcel_id",
          "parcel_ref",
          "tax_year",
          "status",
          "face_amount",
          "delinquent_amount",
          "total_due",
          "interest_rate",
          "bid_rate",
          "sale_date",
          "batch_number",
          "holder_name",
          "redeemed_at",
          "owner_name",
          "site_address_full",
          "legal_description",
          "source_vendor",
          "source_url"
        ]
      },
      "CertificateSaleHit": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "county_slug": {
            "type": "string"
          },
          "tax_year": {
            "type": "integer"
          },
          "vendor": {
            "type": [
              "string",
              "null"
            ]
          },
          "sale_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "sale_date": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "batch_count": {
            "type": "integer"
          },
          "certificate_count": {
            "type": "integer"
          },
          "total_face_amount": {
            "type": [
              "number",
              "null"
            ]
          },
          "total_delinquent_amount": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "county_slug",
          "tax_year",
          "vendor",
          "sale_url",
          "sale_date",
          "status",
          "batch_count",
          "certificate_count",
          "total_face_amount",
          "total_delinquent_amount"
        ]
      },
      "CertificateSaleSearchInput": {
        "type": "object",
        "properties": {
          "county": {
            "allOf": [
              {
                "$ref": "#/components/schemas/multiSelect"
              }
            ]
          },
          "tax_year": {
            "oneOf": [
              {
                "type": "integer"
              },
              {
                "type": "array",
                "items": {
                  "type": "integer"
                }
              }
            ]
          },
          "vendor": {
            "allOf": [
              {
                "$ref": "#/components/schemas/multiSelect"
              }
            ]
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/multiSelect"
              }
            ]
          },
          "sort": {
            "type": "string",
            "enum": [
              "year_newest",
              "year_oldest",
              "face_desc",
              "certificates_desc"
            ]
          },
          "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/certificate-sales/search"
      },
      "CertificateSaleSearchResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CertificateSaleHit"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "pagination",
          "meta"
        ]
      },
      "CertificateSearchInput": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "county": {
            "allOf": [
              {
                "$ref": "#/components/schemas/multiSelect"
              }
            ]
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/multiSelect"
              }
            ]
          },
          "tax_year": {
            "allOf": [
              {
                "$ref": "#/components/schemas/multiSelectInt"
              }
            ]
          },
          "holder": {
            "type": "string",
            "maxLength": 200
          },
          "vendor": {
            "allOf": [
              {
                "$ref": "#/components/schemas/multiSelect"
              }
            ]
          },
          "face_min": {
            "type": "number"
          },
          "face_max": {
            "type": "number"
          },
          "sale_after": {
            "allOf": [
              {
                "$ref": "#/components/schemas/dateString"
              }
            ]
          },
          "sale_before": {
            "allOf": [
              {
                "$ref": "#/components/schemas/dateString"
              }
            ]
          },
          "redeemed": {
            "type": "boolean"
          },
          "sort": {
            "type": "string",
            "enum": [
              "relevance",
              "face_desc",
              "face_asc",
              "year_newest",
              "sale_newest"
            ]
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "default": 25
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "default": 0
          },
          "facets": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40
            }
          }
        },
        "required": [
          "limit",
          "offset"
        ],
        "description": "Query parameters for GET /api/v1/certificates/search"
      },
      "CertificateSearchResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CertificateHit"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/paginationMetaSchema"
          },
          "meta": {
            "$ref": "#/components/schemas/responseMetaSchema"
          }
        },
        "required": [
          "data",
          "pagination",
          "meta"
        ]
      },
      "County": {},
      "CountyList": {},
      "dateString": {
        "type": "string",
        "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
      },
      "DelinquencySourceList": {},
      "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"
        ]
      },
      "HolderHit": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "certificate_count": {
            "type": "integer"
          },
          "county_count": {
            "type": "integer"
          },
          "total_face_amount": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "certificate_count",
          "county_count",
          "total_face_amount"
        ]
      },
      "HolderSearchInput": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "min_certificates": {
            "type": "integer",
            "minimum": 0
          },
          "sort": {
            "type": "string",
            "enum": [
              "count_desc",
              "face_desc",
              "name_asc"
            ]
          },
          "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/holders/search"
      },
      "HolderSearchResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HolderHit"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "pagination",
          "meta"
        ]
      },
      "LandsAvailableHit": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "county_slug": {
            "type": "string"
          },
          "parcel_id": {
            "type": "string"
          },
          "parcel_ref": {
            "type": [
              "string",
              "null"
            ]
          },
          "certificate_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "tax_year": {
            "type": [
              "integer",
              "null"
            ]
          },
          "opening_bid": {
            "type": [
              "number",
              "null"
            ]
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "owner_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "site_address_full": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "county_slug",
          "parcel_id",
          "parcel_ref",
          "certificate_number",
          "tax_year",
          "opening_bid",
          "status",
          "owner_name",
          "site_address_full"
        ]
      },
      "LandsAvailableSearchInput": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "county": {
            "allOf": [
              {
                "$ref": "#/components/schemas/multiSelect"
              }
            ]
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/multiSelect"
              }
            ]
          },
          "max_opening_bid": {
            "type": "number"
          },
          "sort": {
            "type": "string",
            "enum": [
              "bid_asc",
              "bid_desc",
              "year_newest"
            ]
          },
          "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/lands-available/search"
      },
      "LandsAvailableSearchResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LandsAvailableHit"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/PaginationMeta"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "pagination",
          "meta"
        ]
      },
      "multiSelect": {
        "oneOf": [
          {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40
            }
          }
        ]
      },
      "multiSelectInt": {
        "oneOf": [
          {
            "type": "integer"
          },
          {
            "type": "array",
            "items": {
              "type": "integer"
            }
          }
        ]
      },
      "PaginationMeta": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "has_more": {
            "type": "boolean"
          }
        },
        "required": [
          "limit",
          "offset",
          "total",
          "has_more"
        ]
      },
      "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"
                }
              }
            }
          }
        }
      }
    },
    "/certificate-sales/search": {
      "get": {
        "operationId": "get-certificate-sales-search",
        "summary": "Search certificate sales",
        "description": "Search annual county tax-certificate sale events by county, tax year, sale vendor (e.g. lienhub, realauction), and status. Multi-select supported on county, tax_year, vendor, and status.",
        "tags": [
          "Certificate-sales",
          "Certificate Sales"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "county",
            "required": false,
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/multiSelect"
                }
              ]
            }
          },
          {
            "in": "query",
            "name": "tax_year",
            "required": false,
            "schema": {
              "oneOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "integer"
                  }
                }
              ]
            }
          },
          {
            "in": "query",
            "name": "vendor",
            "required": false,
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/multiSelect"
                }
              ]
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/multiSelect"
                }
              ]
            }
          },
          {
            "in": "query",
            "name": "sort",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "year_newest",
                "year_oldest",
                "face_desc",
                "certificates_desc"
              ]
            }
          },
          {
            "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 CertificateSaleHit rows with pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CertificateSaleSearchResponse"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      }
    },
    "/certificates/{id}": {
      "get": {
        "operationId": "get-certificates-{id}",
        "summary": "Get certificate by id",
        "description": "Full detail for a single tax certificate by its internal id. Includes face / delinquent / interest / fee amounts, sale + redemption fields, holder, owner, site address, legal description, and the raw source record.",
        "tags": [
          "Certificates"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "number"
            },
            "example": 123,
            "description": "Path parameter: id"
          }
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Full certificate record.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CertificateHit"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid X-API-Key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Certificate 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"
                }
              }
            }
          }
        }
      }
    },
    "/certificates/by-parcel": {
      "get": {
        "operationId": "get-certificates-by-parcel",
        "summary": "List certificates for a parcel",
        "description": "All tax certificates for a single county parcel, looked up by county slug plus the county-assigned parcel_id (punctuation-insensitive). Returns an empty list (not 404/500) when the parcel has no certificates.",
        "tags": [
          "Certificates"
        ],
        "parameters": [],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "List envelope of CertificateHit rows.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CertificateSearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing county or parcel_id query parameter.",
            "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"
                }
              }
            }
          }
        }
      }
    },
    "/certificates/counts": {
      "get": {
        "operationId": "get-certificates-counts",
        "summary": "Certificate counts by status",
        "description": "Grouped certificate counts by status, optionally scoped to a county slug and/or tax year.",
        "tags": [
          "Certificates"
        ],
        "parameters": [],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Object with the applied scope and an array of { status, count } buckets.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CertificateCounts"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      }
    },
    "/certificates/fields": {
      "get": {
        "operationId": "get-certificates-fields",
        "summary": "List certificate field dictionary",
        "description": "Returns the complete tax-certificate field dictionary — every field that may appear on a certificate record, with a canonical code, human-readable label, category, and value type. Use it to discover everything available and choose the fields you want to consume.",
        "tags": [
          "Certificates"
        ],
        "parameters": [],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Array of field descriptors.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CertificateFieldDictionary"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      }
    },
    "/certificates/freshness": {
      "get": {
        "operationId": "get-certificates-freshness",
        "summary": "Certificate dataset freshness",
        "description": "Snapshot of tax-certificate-dataset freshness — total record count, latest tax year, last ingest timestamp, and last successful source pull.",
        "tags": [
          "Certificates"
        ],
        "parameters": [],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Object with total, latest_tax_year, last_ingested_at, last_source_success_at.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CertificateFreshness"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      }
    },
    "/certificates/search": {
      "get": {
        "operationId": "get-certificates-search",
        "summary": "Search tax certificates",
        "description": "Search Florida tax certificates by certificate number / owner name / site address / parcel id (fuzzy), county, certificate status, tax year, holder/fund name, sale vendor, face-amount range, certificate sale-date range, and redemption state. Multi-select supported on county, status, tax_year, and vendor. Returns optional facet counts.",
        "tags": [
          "Certificates"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          {
            "in": "query",
            "name": "county",
            "required": false,
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/multiSelect"
                }
              ]
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/multiSelect"
                }
              ]
            }
          },
          {
            "in": "query",
            "name": "tax_year",
            "required": false,
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/multiSelectInt"
                }
              ]
            }
          },
          {
            "in": "query",
            "name": "holder",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "in": "query",
            "name": "vendor",
            "required": false,
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/multiSelect"
                }
              ]
            }
          },
          {
            "in": "query",
            "name": "face_min",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "in": "query",
            "name": "face_max",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "in": "query",
            "name": "sale_after",
            "required": false,
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/dateString"
                }
              ]
            }
          },
          {
            "in": "query",
            "name": "sale_before",
            "required": false,
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/dateString"
                }
              ]
            }
          },
          {
            "in": "query",
            "name": "redeemed",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "sort",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "relevance",
                "face_desc",
                "face_asc",
                "year_newest",
                "sale_newest"
              ]
            }
          },
          {
            "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
            }
          },
          {
            "in": "query",
            "name": "facets",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 40
              }
            }
          }
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "List envelope of CertificateHit rows with pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CertificateSearchResponse"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      }
    },
    "/counties": {
      "get": {
        "operationId": "get-counties",
        "summary": "List counties",
        "description": "All counties covered by the dataset, alphabetical by name. Each row carries the county slug and display name plus any modeled coverage metadata.",
        "tags": [
          "Counties"
        ],
        "parameters": [],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Object envelope whose `data` is the array of county rows.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CountyList"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      }
    },
    "/counties/{county}": {
      "get": {
        "operationId": "get-counties-{county}",
        "summary": "Get county by slug",
        "description": "Full record for a single county by its slug (e.g. \"polk\").",
        "tags": [
          "Counties"
        ],
        "parameters": [
          {
            "name": "county",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "example",
            "description": "Path parameter: county"
          }
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Single county record.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/County"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid X-API-Key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "County 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"
                }
              }
            }
          }
        }
      }
    },
    "/holders/{id}": {
      "get": {
        "operationId": "get-holders-{id}",
        "summary": "Get holder by id",
        "description": "Full detail for a single tax-certificate holder / fund by its internal id, including aggregate certificate count and total face amount held.",
        "tags": [
          "Holders"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "number"
            },
            "example": 123,
            "description": "Path parameter: id"
          }
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Full holder record.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HolderHit"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid X-API-Key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Holder 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"
                }
              }
            }
          }
        }
      }
    },
    "/holders/search": {
      "get": {
        "operationId": "get-holders-search",
        "summary": "Search certificate holders",
        "description": "Search tax-certificate holders / funds by name (fuzzy), optionally filtered to holders carrying at least a minimum certificate count. Sortable by certificate count, total face amount, or name.",
        "tags": [
          "Holders"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          {
            "in": "query",
            "name": "min_certificates",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "in": "query",
            "name": "sort",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "count_desc",
                "face_desc",
                "name_asc"
              ]
            }
          },
          {
            "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 HolderHit rows with pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HolderSearchResponse"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      }
    },
    "/lands-available/search": {
      "get": {
        "operationId": "get-lands-available-search",
        "summary": "Search lands available for taxes",
        "description": "Search the \"lands available for taxes\" list (parcels that went unsold at a tax-deed sale) by owner name / site address / parcel id (fuzzy), county, status, and maximum opening bid. Multi-select supported on county and status.",
        "tags": [
          "Lands-available",
          "Lands Available"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          {
            "in": "query",
            "name": "county",
            "required": false,
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/multiSelect"
                }
              ]
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/multiSelect"
                }
              ]
            }
          },
          {
            "in": "query",
            "name": "max_opening_bid",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "in": "query",
            "name": "sort",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "bid_asc",
                "bid_desc",
                "year_newest"
              ]
            }
          },
          {
            "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 LandsAvailableHit rows with pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LandsAvailableSearchResponse"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      }
    },
    "/sample/counties": {
      "get": {
        "operationId": "get-sample-counties",
        "summary": "List counties (sample, no auth)",
        "description": "Open, no-key preview of the counties endpoint. Returns the distinct counties present in the sample certificate dataset. Demo data only.",
        "tags": [
          "Sample"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Object envelope whose `data` is the array of sample county rows.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CountyList"
                }
              }
            }
          }
        }
      }
    },
    "/sample/certificates/{id}": {
      "get": {
        "operationId": "get-sample-certificates-{id}",
        "summary": "Get certificate by id (sample, no auth)",
        "description": "Open, no-key preview of the certificate-detail endpoint. Returns a single sample tax certificate. Demo data only.",
        "tags": [
          "Sample"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "number"
            },
            "example": 123,
            "description": "Path parameter: id"
          }
        ],
        "responses": {
          "200": {
            "description": "Full sample certificate record.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CertificateHit"
                }
              }
            }
          },
          "404": {
            "description": "Sample certificate id not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/sample/certificates/search": {
      "get": {
        "operationId": "get-sample-certificates-search",
        "summary": "Search certificates (sample, no auth)",
        "description": "Open, no-key preview of the certificate-search endpoint. Returns hand-curated Florida sample tax certificates in the same envelope as the paid /certificates/search. Any query (including unknown terms) returns 200 — never an empty error. Demo data only; `meta.dataset_status` is \"sample\".",
        "tags": [
          "Sample"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "List envelope of sample CertificateHit rows.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CertificateSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/sources": {
      "get": {
        "operationId": "get-sources",
        "summary": "List data sources",
        "description": "List the certificate / delinquent-tax feed sources (per county / tax year), optionally filtered by county, vendor, source kind, or active flag.",
        "tags": [
          "Sources"
        ],
        "parameters": [],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "List envelope of source rows.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DelinquencySourceList"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      }
    },
    "/sources/{county}": {
      "get": {
        "operationId": "get-sources-{county}",
        "summary": "List data sources for a county",
        "description": "All certificate / delinquent-tax feed sources configured for a single county slug, newest tax year first. Returns an empty list when none are configured.",
        "tags": [
          "Sources"
        ],
        "parameters": [
          {
            "name": "county",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "example",
            "description": "Path parameter: county"
          }
        ],
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "List envelope of source rows.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DelinquencySourceList"
                }
              }
            }
          },
          "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": "Certificate-sales"
    },
    {
      "name": "Certificates"
    },
    {
      "name": "Counties"
    },
    {
      "name": "Holders"
    },
    {
      "name": "Lands-available"
    },
    {
      "name": "Sample"
    },
    {
      "name": "Sources"
    }
  ]
}