{"openapi":"3.1.0","info":{"title":"AuctionScrapers API","version":"0.1.0","description":"Real property auction data from original sources only (courts, sheriffs, trustees, clerks, recorders, statutory notice portals, government-contracted vendors). Records carry provenance (source link-outs, last_verified_at) and a full lifecycle event history. NOT a consumer reporting agency: no FCRA-permissible-purpose use.\n\nRate limiting: every authenticated response carries X-RateLimit-Limit (requests/minute for your key), X-RateLimit-Remaining, and X-RateLimit-Reset (Unix epoch seconds when the window resets). 429 responses (per-minute limit or monthly quota) include Retry-After (seconds).\n\nSuppression redacts a party NAME; it is not removal. Scope `full` listings never appear anywhere (list and detail return as if the record does not exist). Scope `search_index` listings appear normally in list/search results and by direct id (any search-engine de-indexing is the consumer's concern). Scope `party_names` listings are fully visible with plaintiff and defendant rendered as the literal string \"[redacted]\"; every other field — case_number, court, attorney, trustee_or_officer, legal_description — renders normally. Suppression metadata (the flags themselves) is never returned on any response."},"servers":[{"url":"http://localhost:8787","description":"dev"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key"}},"headers":{"XRateLimitLimit":{"description":"Request-per-minute limit for the presented API key","schema":{"type":"integer"}},"XRateLimitRemaining":{"description":"Requests remaining in the current one-minute window","schema":{"type":"integer"}},"XRateLimitReset":{"description":"Unix epoch seconds at which the current window resets","schema":{"type":"integer"}}},"responses":{"RateLimited":{"description":"Per-minute rate limit or monthly quota exceeded. Retry-After gives seconds until the window (or calendar month) resets.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"schemas":{"Listing":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"county_fips":{"type":"string"},"county_name":{"type":"string"},"state":{"type":"string"},"record_type":{"type":"string","enum":["foreclosure","tax_deed","tax_lien","execution","federal_sale","lis_pendens","nod"]},"status":{"type":"string","enum":["scheduled","postponed_tbd","canceled","sold","upset_period","delisted_unconfirmed","active","withdrawn","superseded","stale"]},"sale_datetime":{"type":["string","null"],"format":"date-time"},"sale_timezone":{"type":["string","null"],"description":"IANA timezone the sale is conducted in (e.g. America/New_York); null until populated"},"sale_location":{"type":["string","null"]},"property_class":{"type":"string"},"has_address":{"type":"boolean"},"address_raw":{"type":["string","null"]},"unit_number":{"type":["string","null"]},"city":{"type":["string","null"]},"zip":{"type":["string","null"]},"apn":{"type":["string","null"]},"lat":{"type":["number","null"],"description":"WGS84 latitude; null until geocoded"},"lng":{"type":["number","null"],"description":"WGS84 longitude; null until geocoded"},"case_number":{"type":["string","null"]},"court":{"type":["string","null"]},"plaintiff":{"type":["string","null"],"description":"Rendered as the literal \"[redacted]\" when suppression_scope=party_names"},"defendant":{"type":["string","null"],"description":"Rendered as the literal \"[redacted]\" when suppression_scope=party_names"},"attorney":{"type":["string","null"]},"trustee_or_officer":{"type":["string","null"]},"opening_bid":{"type":["number","null"]},"judgment_amount":{"type":["number","null"]},"sold_price":{"type":["number","null"]},"sold_at":{"type":["string","null"],"format":"date-time"},"assessed_value":{"type":["number","null"],"description":"County-assessor assessed value (USD). Null until populated by a future enrichment pipeline."},"estimated_value":{"type":["number","null"],"description":"Estimated market value (USD). Null until populated by a future enrichment pipeline."},"first_seen_at":{"type":"string","format":"date-time"},"last_verified_at":{"type":["string","null"],"format":"date-time"},"previous_listing_id":{"type":["string","null"],"format":"uuid"}}},"SearchResult":{"type":"object","description":"One omni-search suggestion. `type` tells the consumer how to render and route it; `href_params` are the query params to replay against /v1/listings (or /v1/counties) to drill in.","properties":{"type":{"type":"string","enum":["county","state","city","listing"],"description":"county = county matched by name; state = US state matched by name/abbr; city = distinct listing city; listing = a specific listing matched by street address OR party name (both route to one listing)."},"label":{"type":"string","description":"Primary display text (county/state/city name, street address, or matched party name). Never a redacted party name — party_names-suppressed rows are excluded from name matching."},"sublabel":{"type":["string","null"],"description":"Secondary display text (e.g. state code for a county, \"City, ST ZIP\" for a listing)."},"href_params":{"type":"object","additionalProperties":{"type":"string"},"description":"Params to route the suggestion: {state} | {county_fips} | {city,state} for reference kinds, {id} for a listing."}}},"County":{"type":"object","properties":{"fips":{"type":"string","description":"5-digit county FIPS code"},"name":{"type":"string"},"state":{"type":"string","description":"USPS state code"},"timezone":{"type":"string","description":"IANA timezone used for sale-local scheduling"},"housing_units_2020":{"type":["integer","null"],"description":"2020 Census housing units"}}},"ListingDetail":{"allOf":[{"$ref":"#/components/schemas/Listing"},{"type":"object","properties":{"legal_description":{"type":["string","null"]},"filed_date":{"type":["string","null"],"format":"date"},"postponement_count":{"type":"integer"},"events":{"type":"array","items":{"type":"object","properties":{"event_type":{"type":"string"},"old_value":{},"new_value":{},"detected_at":{"type":"string","format":"date-time"}}}},"sources":{"type":"array","description":"Provenance: every original source this record was seen on.","items":{"type":"object","properties":{"source_id":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string"},"source_url":{"type":"string"},"first_seen_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"}}}}}}]}}},"paths":{"/v1/listings":{"get":{"summary":"Search listings","description":"Cursor-paginated search. Only scope `full` suppressions are excluded; `search_index` rows appear normally like any other listing; scope `party_names` rows appear with plaintiff/defendant rendered as \"[redacted]\" (all other fields normal).","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Address search: case-insensitive substring match over the normalized (and raw) street address"},{"name":"state","in":"query","schema":{"type":"string"},"description":"USPS state code"},{"name":"county_fips","in":"query","schema":{"type":"string"}},{"name":"record_type","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"},"description":"comma-separated"},{"name":"city","in":"query","schema":{"type":"string"}},{"name":"zip","in":"query","schema":{"type":"string"}},{"name":"sale_after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"sale_before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"has_address","in":"query","schema":{"type":"boolean"}},{"name":"property_class","in":"query","schema":{"type":"string"},"description":"comma-separated"},{"name":"limit","in":"query","schema":{"type":"integer","maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"opaque keyset cursor"}],"responses":{"200":{"description":"Paginated listings","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"total":{"type":"integer","description":"Exact count of listings matching the filter set (cursor-independent; stable across pages)"},"next_cursor":{"type":["string","null"]}}}}}},"400":{"description":"Invalid cursor or parameters"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/listings/{id}":{"get":{"summary":"Listing detail with full event history and provenance","description":"Direct lookup by id. Returns 404 only for scope `full` suppressions; `search_index` and `party_names` listings are returned (party_names with plaintiff/defendant rendered as \"[redacted]\", all other fields normal).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Listing detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingDetail"}}}},"404":{"description":"Not found (or fully suppressed)"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/search":{"get":{"summary":"Unified omni-search / typeahead across counties, states, cities, and listings","description":"One query fans out across counties (name), states (name/abbr), cities (distinct listing city), and listings (street address or party name). Returns a ranked, categorized suggestion list for a consumer search box. Ranking: exact/prefix matches ahead of fuzzy (trigram); more-populous counties and more-active cities first. Bounded by `limit` (default 10, max 25) with a minimum query length of 2.\n\nSuppression (amendment #14): scope `full` listings never appear. A scope `party_names` listing stays findable by address/city/ZIP (public) but is NEVER findable by its redacted party name and its redacted name is never returned as a label — the party-name matcher excludes those rows entirely.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2},"description":"Search term: address, city, county, state, ZIP, or party name. Minimum 2 characters."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":10},"description":"Max results across all kinds."}],"responses":{"200":{"description":"Ranked, categorized suggestions","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}},"total":{"type":"integer","description":"Number of results returned (== results.length; bounded by limit)."}}}}}},"400":{"description":"Missing/short query (< 2 chars) or invalid limit"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/counties":{"get":{"summary":"County reference list","description":"Reference geography: county FIPS, name, state, IANA timezone, 2020 housing units. Not paginated.","parameters":[{"name":"state","in":"query","schema":{"type":"string"},"description":"USPS state code filter"}],"responses":{"200":{"description":"Counties","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/County"}},"total":{"type":"integer"}}}}}},"400":{"description":"Invalid state code"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/counties/{fips}":{"get":{"summary":"County lookup by FIPS","parameters":[{"name":"fips","in":"path","required":true,"schema":{"type":"string"},"description":"5-digit county FIPS"}],"responses":{"200":{"description":"County","content":{"application/json":{"schema":{"$ref":"#/components/schemas/County"}}}},"400":{"description":"Malformed FIPS code"},"404":{"description":"Unknown FIPS"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/sources":{"get":{"summary":"Source registry with health and verification status","parameters":[{"name":"state","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Sources"}}}},"/v1/coverage":{"get":{"summary":"Coverage transparency: listing coverage and status/alert coverage, national and per state","responses":{"200":{"description":"Coverage stats"}}}}}}