{"openapi":"3.1.0","info":{"title":"DirtSignal API","version":"0.2.0","description":"Public records intelligence for real estate acquisition. Code violations, active lien signals, judgments, and lis pendens across Florida counties."},"servers":[{"url":"https://dirtsignal.com","description":"Production"}],"paths":{"/api/v1/coverage":{"get":{"operationId":"checkCoverage","summary":"Check ZIP coverage","description":"Returns whether DirtSignal has imported event records in a 5-digit ZIP, with the approximate record lookback age. This is a coverage signal only; it is not a title search, lien search, or guarantee that no records exist.","parameters":[{"name":"zip","in":"query","schema":{"type":"string","example":"33602"},"description":"5-digit ZIP code. Either zip or address is accepted."},{"name":"address","in":"query","schema":{"type":"string","example":"2309 N Riverside Dr Tampa FL 33602"},"description":"Address text containing a 5-digit ZIP. Used when zip is omitted."},{"name":"type","in":"query","schema":{"type":"string","example":"code,sm"},"description":"Optional comma-separated coverage source type filter: code, clerk, or sm. Special magistrate coverage is only returned by sm."}],"responses":{"200":{"description":"Coverage result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZipCoverage"}}}},"400":{"description":"Invalid coverage type filter"}}}},"/api/v1/events":{"get":{"operationId":"listEvents","summary":"List events","description":"Returns normalized events filtered by region and record type. By default, clerk documents are narrowed to active distress signals such as liens, judgments, and lis pendens. Requires a paid account and an API key from Settings.","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"region","in":"query","schema":{"type":"string","example":"tampa-bay"},"description":"Region slug. Limits results to the region's source_ids."},{"name":"view_id","in":"query","schema":{"type":"string","example":"view_..."},"description":"Run a named saved view. Its multi-region, city, signal, parcel-size, weak-signal, filter, and sort definition is applied."},{"name":"types","in":"query","schema":{"type":"string","example":"violation,clerk_document"},"description":"Comma-separated record_type filter."},{"name":"limit","in":"query","schema":{"type":"integer","default":15000,"maximum":50000},"description":"Max events to return."},{"name":"include_inactive","in":"query","schema":{"type":"string","enum":["1"]},"description":"Pass 1 to include closed violations and broad clerk documents such as deeds, mortgages, satisfactions, and releases."},{"name":"include_weak","in":"query","schema":{"type":"string","enum":["1"]},"description":"Alias for include_inactive. Used by the dashboard's 'Show weak records' toggle."}],"responses":{"200":{"description":"Event list","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"total":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Paid account required"}}}},"/api/v1/saved-views":{"get":{"operationId":"listSavedViews","summary":"List named report views","security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"Saved views"},"401":{"description":"Unauthorized"}}},"post":{"operationId":"saveSavedView","summary":"Create or update a named report view","security":[{"apiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedViewInput"}}}},"responses":{"200":{"description":"Saved view"},"400":{"description":"Invalid definition"},"401":{"description":"Unauthorized"}}}},"/api/v1/saved-views/{viewId}/briefs":{"get":{"operationId":"listSavedViewBriefs","summary":"List generated custom briefs","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"viewId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Generated brief artifacts"}}},"post":{"operationId":"generateSavedViewBrief","summary":"Queue a custom brief","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"viewId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Brief generation queued"}}}},"/api/v1/property-workflow":{"get":{"operationId":"getPropertyWorkflow","summary":"Get property workflow and activity","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"address_key","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Property workspace and activity"}}},"post":{"operationId":"updatePropertyWorkflow","summary":"Update property status, notes, calls, visits, or follow-up","security":[{"apiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyWorkflowAction"}}}},"responses":{"200":{"description":"Updated property workspace and activity"}}}},"/api/v1/property/coverage":{"get":{"operationId":"getPropertyCoverageWindow","summary":"Check code-record coverage for a city or ZIP","description":"Returns indexed code-record coverage for a ZIP or city/state and whether a healthy portal supports a broader realtime address search of up to five years. Supply either zip or both city and state. This request is tracked but never billable. Internal region slugs are not required or returned.","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"city","in":"query","required":false,"schema":{"type":"string","example":"Tampa"}},{"name":"state","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"example":"FL"}},{"name":"zip","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{5}$","example":"33602"}}],"responses":{"200":{"description":"City/state indexed coverage, realtime-search availability, and portal health"},"400":{"description":"A valid ZIP or city and two-letter state are required"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Property API access required"}}}},"/api/v1/property/search":{"get":{"operationId":"searchPropertyCodeViolations","summary":"Search one property for code-violation records","description":"Returns indexed records for one address. The default is indexed-only; set `live_search=true` to query every eligible portal covering the property. Indexed records remain in the response when an optional live search is unavailable or fails, with details in `live_search.message`. A `202` response means portal work is pending—retry the identical request with the same `Idempotency-Key` after `retry_after_seconds`. Successful intervals, including zero-result searches, are memoized per property and portal, so later searches pull only missing coverage. Statuses: `complete` = all portals finished, `complete_with_errors` = indexed results plus a live-search error, `pending` = indexed results plus unfinished live work, `unavailable` = indexed results with no healthy live portal. One idempotency key creates one customer search even when several portals are queried.","x-codeSamples":[{"lang":"Shell","label":"Live property search","source":"curl --get 'https://dirtsignal.com/api/v1/property/search' \\\n  -H 'Authorization: Bearer ds_your_key' \\\n  -H 'Idempotency-Key: order-123' \\\n  --data-urlencode 'address=2309 N Riverside Dr' \\\n  --data-urlencode 'city=Tampa' \\\n  --data-urlencode 'state=FL' \\\n  --data-urlencode 'live_search=true'"}],"security":[{"apiKeyAuth":[]}],"parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string","example":"2309 N Riverside Dr"}},{"name":"city","in":"query","required":true,"schema":{"type":"string","example":"Tampa"}},{"name":"state","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":2,"example":"FL"}},{"name":"live_search","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Explicit opt-in for the broader public-portal query. The default indexed-only search never contacts a live portal."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Recommended unique client request ID. Retrying with the same key reuses the original usage event and does not create a second billable search."}],"responses":{"200":{"description":"Property search result and billing usage ID"},"202":{"description":"Indexed results returned; retry the identical request with the same Idempotency-Key after retry_after_seconds"},"400":{"description":"A specific address is required"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Property API access required"}}}},"/api/v1/property/certificate":{"post":{"operationId":"createClearPropertyCertificate","summary":"Create a branded clear-result PDF certificate","description":"Creates a base64-encoded PDF from a prior zero-result property search. Certificate generation is not a second billable search.","security":[{"apiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["search_id"],"properties":{"search_id":{"type":"string","example":"usage_..."}}}}}},"responses":{"200":{"description":"Base64-encoded application/pdf certificate"},"401":{"description":"Missing or invalid API key"},"409":{"description":"The referenced search returned records"}}}},"/api/v1/briefs/{slug}":{"get":{"operationId":"getBrief","summary":"Get latest ranked brief","description":"Returns the latest stored ranked brief for a region. Briefs are pre-composed and include ranked top picks, summary copy, generated window metadata, and event snapshots when available. Requires a paid account and an API key from Settings.","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","example":"tampa-bay"},"description":"Region slug."},{"name":"window","in":"query","schema":{"type":"string","enum":["weekly","daily"],"default":"weekly"},"description":"Stored brief window to return."}],"responses":{"200":{"description":"Stored ranked brief","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefResponse"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Paid account required"},"404":{"description":"Unknown region or no stored brief for the selected window"}}}}},"components":{"schemas":{"SavedViewInput":{"type":"object","required":["name","definition"],"properties":{"view_id":{"type":"string"},"name":{"type":"string"},"definition":{"type":"object","required":["region_slugs"],"properties":{"region_slugs":{"type":"array","items":{"type":"string"}},"cities":{"type":"array","items":{"type":"string"}},"record_types":{"type":"array","items":{"type":"string"}},"exclude_signals":{"type":"array","items":{"type":"string"}},"min_parcel_size":{"type":"number","nullable":true},"max_parcel_size":{"type":"number","nullable":true},"include_weak":{"type":"boolean"}}},"brief":{"type":"object","properties":{"enabled":{"type":"boolean"},"frequency":{"type":"string","enum":["daily","weekly"]},"email":{"type":"string","format":"email","nullable":true}}}}},"PropertyWorkflowAction":{"type":"object","required":["address_key","action"],"properties":{"address_key":{"type":"string"},"address_label":{"type":"string"},"region_slug":{"type":"string"},"action":{"type":"string","enum":["set_status","add_note","log_call","log_visit","set_follow_up"]},"status":{"type":"string","enum":["new","reviewing","qualified","follow_up","nurture","passed"]},"note":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"next_follow_up_at":{"type":"string","format":"date-time","nullable":true}}},"BriefResponse":{"type":"object","properties":{"region":{"type":"object","properties":{"slug":{"type":"string","example":"tampa-bay"},"display_name":{"type":"string","example":"Tampa Bay, FL"},"timezone":{"type":"string","example":"America/New_York"}}},"generated_for":{"type":"string","example":"2026-04-15"},"generated_at":{"type":"string","format":"date-time"},"model":{"type":"string","example":"gpt-5.4-mini"},"window_kind":{"type":"string","enum":["weekly","daily"]},"payload":{"$ref":"#/components/schemas/BriefPayload"}}},"BriefPayload":{"type":"object","properties":{"local_lede":{"type":"string"},"summary":{"type":"string"},"coverage_update":{"type":"string"},"top_picks":{"type":"array","items":{"$ref":"#/components/schemas/BriefPick"}},"stats":{"type":"object","properties":{"region_slug":{"type":"string","example":"tampa-bay"},"total_events":{"type":"integer"},"window_since":{"type":"string","format":"date-time"},"window_until":{"type":"string","format":"date-time"},"generated_at":{"type":"string","format":"date-time"}}}}},"BriefPick":{"type":"object","properties":{"source_local_id":{"type":"string","example":"HC-CE-2026-001234"},"rank":{"type":"integer","example":1},"why_it_matters":{"type":"string"},"event_snapshot":{"type":"object","properties":{"address_key":{"type":"string","nullable":true},"address_raw":{"type":"string","nullable":true},"event_subtype":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"source_url":{"type":"string","nullable":true},"owner_name":{"type":"string","nullable":true}}}}},"Event":{"type":"object","properties":{"source_id":{"type":"string","example":"us_fl_hillsborough_county_accela"},"source_local_id":{"type":"string","example":"HC-CE-2026-001234"},"source_url":{"type":"string","nullable":true},"record_type":{"type":"string","enum":["violation","clerk_document"]},"event_subtype":{"type":"string","nullable":true,"example":"Remedial Order"},"status":{"type":"string","nullable":true,"example":"Open"},"address_raw":{"type":"string","nullable":true,"example":"4710 E Broadway Ave Tampa FL 33605"},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"subject":{"type":"string","nullable":true,"description":"Best display target: violation address, or lien debtor/owner when no address exists."},"detail":{"type":"string","nullable":true,"description":"Compact display detail for the dashboard."},"signal_label":{"type":"string","enum":["Violation","Lien signal","Planning application"]},"signal_class":{"type":"string","enum":["violation","lien","planning"]},"is_weak":{"type":"boolean","description":"True for rows hidden from the default product view unless include_weak=1 is passed."},"date":{"type":"string","format":"date-time","nullable":true},"party_1":{"type":"string","nullable":true,"description":"Grantor / creditor (clerk docs)"},"party_2":{"type":"string","nullable":true,"description":"Grantee / debtor (clerk docs)"},"consideration":{"type":"string","nullable":true,"description":"Dollar amount when the source exposes one."}}},"ZipCoverage":{"type":"object","properties":{"zip":{"type":"string","nullable":true,"example":"33602"},"covered":{"type":"boolean","nullable":true,"description":"True when imported event records exist in this ZIP; false when a ZIP was supplied and no imported rows exist; null when no ZIP could be parsed."},"oldest_record_at":{"type":"string","nullable":true,"description":"Oldest event date found for the returned coverage sources."},"lookback_label":{"type":"string","nullable":true,"example":"in the last 4 months"},"message":{"type":"string","nullable":true,"example":"ZIP 33602 is covered by DirtSignal's imported records in the last 4 months."},"regions":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","example":"tampa-bay"},"name":{"type":"string","example":"Tampa Bay, FL"}}}},"types":{"type":"array","description":"Coverage source types present in the returned, filtered sources.","items":{"type":"string","enum":["code","clerk","sm"]}},"sources":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"string","example":"us_fl_tampa_accela"},"jurisdiction":{"type":"string","example":"Tampa, FL"},"type":{"type":"string","enum":["code","clerk","sm"],"example":"code"},"region_slug":{"type":"string","nullable":true,"example":"tampa-bay"},"region_name":{"type":"string","nullable":true,"example":"Tampa Bay, FL"},"oldest_record_at":{"type":"string","nullable":true},"most_recent":{"type":"string","nullable":true}}}}}}},"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"DirtSignal API key","description":"Generate an API key in Settings and pass it as Authorization: Bearer ds_..."}}}}