{"openapi":"3.1.0","info":{"title":"SOS.city public-records API","version":"1.5.0","summary":"The public record for every place, organised: power, water, emergencies, police, fire and EMS, laws, permits, funding and grants.","description":"Every source links to its publisher's original, with its licence, update rate and when we last checked it. Free without a key (anonymous daily limits); an API key raises limits, and credits or x402 pay for full history, bulk queries, city data packs and building records. Agents may show a verified human stands behind them with a 5arz proof-of-personhood credential in the X-5arz-Personhood header (optional; recorded with purchases, never required for access). Not a consumer reporting agency: the data may not be used for tenant, employment, credit or insurance screening, or to locate or profile anyone. Not an emergency service.","termsOfService":"https://sos.city/legal/data-use","contact":{"name":"SOS.city","url":"https://sos.city/connect","email":"info@5arz.com"}},"externalDocs":{"description":"Docs, plans and MCP","url":"https://sos.city/api"},"servers":[{"url":"https://api.sos.city"}],"security":[{},{"bearer":[]}],"tags":[{"name":"library"},{"name":"records"},{"name":"compliance"},{"name":"store"},{"name":"requests"},{"name":"account"}],"paths":{"/v1/audits/{id}":{"get":{"tags":["account"],"operationId":"getLandlineAudit","summary":"A Landline Audit order by its bearer link (id plus t=token from the buyer's email): status, due date, what's on the lines, and the written plan once delivered. Start one with POST /v1/checkout {product: \"landline_audit\", email, address, zip, wire_center, lines: [{use, count, note}], agree_terms, agree_data_use}: $49, California buildings.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"t","in":"query","required":true,"description":"The token from the email","schema":{"type":"string"}}],"responses":{"200":{"description":"The audit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}}},"/v1/me":{"get":{"tags":["account"],"operationId":"getMe","summary":"Your desk: who you are, your role, plan limits, seats and what you may do","security":[{"bearer":[]}],"responses":{"200":{"description":"You","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}},"post":{"tags":["account"],"operationId":"updateMe","summary":"Update your name; owners and admins also set company, time zone and newsletter opt-out","security":[{"bearer":[]}],"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}}},"/v1/me/widgets":{"get":{"tags":["account"],"operationId":"getWidgets","summary":"Every desk widget with its data, source, freshness and any plan gate, plus offers that fit the account","security":[{"bearer":[]}],"responses":{"200":{"description":"Widgets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}}},"/v1/me/layout":{"get":{"tags":["account"],"operationId":"getLayout","summary":"Your saved desk layout","security":[{"bearer":[]}],"responses":{"200":{"description":"Layout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}},"post":{"tags":["account"],"operationId":"saveLayout","summary":"Save your desk layout: [{id, size S|M|L|XL, hidden}]","security":[{"bearer":[]}],"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}}},"/v1/me/export":{"get":{"tags":["account"],"operationId":"bulkExport","summary":"Pro: every reusable record for a place, full history, as JSON or CSV (up to 50,000 rows)","security":[{"bearer":[]}],"parameters":[{"name":"place","in":"query","required":true,"description":"Place id","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"json | csv","schema":{"type":"string"}}],"responses":{"200":{"description":"Records","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}}},"/v1/me/delete":{"post":{"tags":["account"],"operationId":"deleteAccount","summary":"Owner only: cancel billing, revoke keys, stop alerts and erase the account's details. Send {confirm: <account email>}","security":[{"bearer":[]}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}}},"/v1/team":{"get":{"tags":["account"],"operationId":"getTeam","summary":"The owner, members, invites and seats (Free and Local 1, Business 5, Pro 15; extra seats $10 a month)","security":[{"bearer":[]}],"responses":{"200":{"description":"Team","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}}},"/v1/team/invite":{"post":{"tags":["account"],"operationId":"inviteMember","summary":"Owner or admin: invite {email, role admin|member}. 402 seat_limit when every seat is used","security":[{"bearer":[]}],"responses":{"200":{"description":"Invited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}}},"/v1/billing/seats":{"post":{"tags":["account"],"operationId":"setSeats","summary":"Owner or admin on Business or Pro: set {extra} seats on the Stripe subscription, pro-rated","security":[{"bearer":[]}],"responses":{"200":{"description":"Seats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}}},"/v1/search":{"get":{"tags":["library"],"operationId":"search","summary":"Ask the library a question in plain words","parameters":[{"name":"q","in":"query","required":true,"description":"The question, e.g. 'boil water notice'","schema":{"type":"string"}},{"name":"place","in":"query","required":false,"description":"Place id, e.g. us-ca-los-angeles","schema":{"type":"string"}},{"name":"department","in":"query","required":false,"description":"Department id, e.g. water","schema":{"type":"string"}}],"responses":{"200":{"description":"Matching sources; found=false adds the question to the gap board","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/sources":{"get":{"tags":["library"],"operationId":"listSources","summary":"List sources by place, department or words","parameters":[{"name":"q","in":"query","required":false,"description":"Words","schema":{"type":"string"}},{"name":"place","in":"query","required":false,"description":"Place id; includes everything above it that covers it","schema":{"type":"string"}},{"name":"department","in":"query","required":false,"description":"Department id","schema":{"type":"string"}},{"name":"checked","in":"query","required":false,"description":"Opened | Search only | Not checked","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1-100","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Paging","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Sources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/sources/{id}":{"get":{"tags":["library"],"operationId":"getSource","summary":"One source with publisher, original link, licence and check history","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"The source","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Source"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/places":{"get":{"tags":["library"],"operationId":"listPlaces","summary":"The atlas: world, countries, states, every US county and cities (paged: follow next)","parameters":[{"name":"parent","in":"query","required":false,"description":"Parent place id","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"country | state | county | city","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Rows per page, 1-5000 (default 1000)","schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"description":"Rows to skip","schema":{"type":"string"}}],"responses":{"200":{"description":"Places, with total and next","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}}},"/v1/weather":{"get":{"tags":["library"],"operationId":"countyWeather","summary":"National Weather Service alerts in force now for one US county (5-minute cache)","parameters":[{"name":"county","in":"query","required":false,"description":"5-digit county FIPS, e.g. 06037","schema":{"type":"string"}}],"responses":{"200":{"description":"Active alerts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}}},"/v1/departments":{"get":{"tags":["library"],"operationId":"listDepartments","summary":"The 15 departments every source sits on","responses":{"200":{"description":"Departments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}}},"/v1/gaps":{"get":{"tags":["library"],"operationId":"listGaps","summary":"Records people need that the library doesn't hold yet","parameters":[{"name":"place","in":"query","required":false,"description":"Place id","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"open | researching | no_public_source | found","schema":{"type":"string"}}],"responses":{"200":{"description":"Gaps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}}}}},"/v1/records":{"get":{"tags":["records"],"operationId":"searchRecords","summary":"The records themselves: permits, code cases, inspections, business registrations, grants, weather alerts, earthquakes","description":"Free within the plan's history (Free: 30 days) and 100 rows. full_history=1 costs 1 credit; each 100 rows past the first 100 costs 1 credit (up to 1,000). Pay with an API key's credits or x402.","parameters":[{"name":"place","in":"query","required":false,"description":"Place id","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"Record kind","schema":{"type":"string","enum":["permit","code_case","inspection","cofo","business","grant","weather_alert","earthquake","wildfire","power_shutoff","fire_detection","bank_branch","drug_shortage","lights_drop"]}},{"name":"zip","in":"query","required":false,"description":"Five-digit ZIP","schema":{"type":"string"}},{"name":"address","in":"query","required":false,"description":"Street address with house number","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"YYYY-MM-DD","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","required":false,"description":"1-1000 (over 100 is paid)","schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","required":false,"description":"Paging","schema":{"type":"integer"}},{"name":"full_history","in":"query","required":false,"description":"1 = past the plan's history window (paid)","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Records, each with the agency's original link, its source page (source_url), licence and credit: the acknowledgment the publisher asks for. Quote `credit` with anything you publish from a record; `credits` lists each one once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/requests":{"post":{"tags":["requests"],"operationId":"createRequest","summary":"Ask for a record the library doesn't hold (free), or a paid deep search (quoted first)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question"],"properties":{"kind":{"type":"string","description":"data_request (free) or deep_search (quoted, from $29)","enum":["data_request","deep_search"]},"question":{"type":"string"},"place":{"type":"string"},"email":{"type":"string","description":"To hear back; required for deep_search"}}}}}},"responses":{"201":{"description":"Created"},"400":{"$ref":"#/components/responses/Error"}}}},"/v1/store":{"get":{"tags":["store"],"operationId":"getStore","summary":"Prices and every way to pay (credits, x402, Stripe)","responses":{"200":{"description":"The catalogue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}}}}},"/v1/store/balance":{"get":{"tags":["store"],"operationId":"getBalance","summary":"Credit balance for the API key","security":[{"bearer":[]}],"responses":{"200":{"description":"Balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}}}}},"/v1/store/checkout":{"post":{"tags":["store"],"operationId":"startCheckout","summary":"Buy credits, a city data pack or a whole compliance list: returns a Stripe link for a person and a status_url to poll","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product","email","agree_data_use"],"properties":{"product":{"type":"string","description":"credits_1k ($10), credits_10k ($79), city_pack ($29), compliance_list ($99)","enum":["credits_1k","credits_10k","city_pack","compliance_list"]},"email":{"type":"string","description":"The person who pays"},"place":{"type":"string","description":"For city_pack"},"list":{"type":"string","description":"For compliance_list: a list id from /v1/compliance"},"agree_data_use":{"type":"boolean","description":"Must be true: no screening or profiling people"}}}}}},"responses":{"201":{"description":"Checkout started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"}}}},"/v1/store/orders/{id}":{"get":{"tags":["store"],"operationId":"getOrder","summary":"Order status; when paid, the key-claim link or pack links","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"t","in":"query","required":true,"description":"Order token from status_url","schema":{"type":"string"}}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}}}}},"/v1/store/lists/{list}":{"get":{"tags":["store"],"operationId":"getPaidComplianceList","summary":"A whole compliance list as CSV, opened with a paid compliance_list order token (90 days)","parameters":[{"name":"list","in":"path","required":true,"schema":{"type":"string"}},{"name":"t","in":"query","required":true,"description":"Paid order token","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/store/packs/{place}":{"get":{"tags":["store"],"operationId":"getCityPack","summary":"City data pack (2900 credits, x402, or a paid order link)","parameters":[{"name":"place","in":"path","required":true,"schema":{"type":"string"}},{"name":"t","in":"query","required":false,"description":"Paid order token, instead of credits or x402","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"json (default) or csv (sources only)","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"The pack","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/packet":{"get":{"tags":["packet"],"operationId":"getApprovalPacket","summary":"Emergency purchasing packet (free): for a county with a federal disaster or emergency declaration in the last 365 days, the declarations (OpenFEMA), the federal emergency-procurement rule (2 CFR 200.320(c)(3)) and the documents FEMA asks for, each with its source. Without county, lists tracked counties with a recent declaration. Research, not legal advice or an approval","parameters":[{"name":"county","in":"query","required":false,"description":"Five-digit county FIPS code, e.g. 06037","schema":{"type":"string"}}],"responses":{"200":{"description":"The packet, or the list of counties","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/packet/prices":{"get":{"tags":["packet"],"operationId":"getPacketPrices","summary":"Comparable past federal contracts for what you are buying, performed in the county in the last 3 years (USAspending), with the median, lowest and highest amount. Amounts are whole-award obligations, not unit prices. Metered as an API call","parameters":[{"name":"county","in":"query","required":true,"description":"Five-digit county FIPS code","schema":{"type":"string"}},{"name":"q","in":"query","required":true,"description":"What you are buying, 3-60 characters","schema":{"type":"string"}}],"responses":{"200":{"description":"Awards and their spread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/compliance":{"get":{"tags":["compliance"],"operationId":"listCompliance","summary":"Compliance lists: buildings and facilities that owe a legally required inspection, filing or fix, with what each law requires and how many are on each list (free)","responses":{"200":{"description":"Every list, with its law, who may sign, row count and when it was refreshed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/compliance/check":{"get":{"tags":["compliance"],"operationId":"checkComplianceAddress","summary":"Is this address on any compliance list? One street address against every list at once, with the agency's status, dates and record link (free, 40 a day)","parameters":[{"name":"address","in":"query","required":true,"description":"Street address with a house number, e.g. 200 N Spring St","schema":{"type":"string"}},{"name":"zip","in":"query","required":false,"description":"5-digit ZIP; without it the same number and street name in another ZIP can match","schema":{"type":"string"}}],"responses":{"200":{"description":"Which lists name the address, and what each list is","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/compliance/report":{"get":{"tags":["compliance"],"operationId":"getComplianceReport","summary":"One list's numbers: total, by ZIP, by status and type, and how many addresses are on other lists too (free)","parameters":[{"name":"list","in":"query","required":true,"description":"List id","schema":{"type":"string","enum":["sb721-cited","ebewe-not-complied","code-cases-open","soft-story-open","ndc-concrete","stormwater-facilities"]}}],"responses":{"200":{"description":"The numbers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/compliance/items":{"get":{"tags":["compliance"],"operationId":"getComplianceItems","summary":"Rows of one list. First 10 free; then 100 credits per 100 rows, or 9900 credits for the whole list (all=1); x402 works too","parameters":[{"name":"list","in":"query","required":true,"description":"List id","schema":{"type":"string","enum":["sb721-cited","ebewe-not-complied","code-cases-open","soft-story-open","ndc-concrete","stormwater-facilities"]}},{"name":"zip","in":"query","required":false,"description":"Five-digit ZIP","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Address or part of one","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Exact status","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Exact type","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"Only rows dated on or after (YYYY-MM-DD)","schema":{"type":"string"}},{"name":"stacked","in":"query","required":false,"description":"1 = only addresses on more than one list","schema":{"type":"string","enum":["1"]}},{"name":"limit","in":"query","required":false,"description":"Rows (1-1,000)","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Rows to skip","schema":{"type":"integer"}},{"name":"all","in":"query","required":false,"description":"1 = the whole list","schema":{"type":"string","enum":["1"]}},{"name":"format","in":"query","required":false,"description":"json (default) or csv","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"Rows, each with the agency's id and a link to the original","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/compliance/weekly":{"get":{"tags":["compliance"],"operationId":"getComplianceWeekly","summary":"The weekly report (free): per list, what was added, taken off and changed this week, an 8-week trend, the ZIPs with the most new items, and whether each list is fresh. Counts only, no addresses","parameters":[{"name":"weeks","in":"query","required":false,"description":"Weeks of trend (1-26, default 8)","schema":{"type":"integer"}},{"name":"end","in":"query","required":false,"description":"Last day of the week (YYYY-MM-DD, default today)","schema":{"type":"string"}}],"responses":{"200":{"description":"Every list's week","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/compliance/changes":{"get":{"tags":["compliance"],"operationId":"getComplianceChanges","summary":"What changed on one list since a day (default 7 days): added, off the agency's list, or changed (status, due date, date), with before and after. Counts and the first 10 rows free; then 100 credits per 100 rows. Addresses on other lists come first","parameters":[{"name":"list","in":"query","required":true,"description":"List id","schema":{"type":"string","enum":["sb721-cited","ebewe-not-complied","code-cases-open","soft-story-open","ndc-concrete","stormwater-facilities"]}},{"name":"since","in":"query","required":false,"description":"YYYY-MM-DD (default 7 days ago)","schema":{"type":"string"}},{"name":"until","in":"query","required":false,"description":"YYYY-MM-DD","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"added, removed, changed (comma-separated)","schema":{"type":"string"}},{"name":"zip","in":"query","required":false,"description":"One or more ZIPs, comma-separated","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Exact status","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Exact type","schema":{"type":"string"}},{"name":"stacked","in":"query","required":false,"description":"1 = only addresses on more than one list","schema":{"type":"string","enum":["1"]}},{"name":"limit","in":"query","required":false,"description":"Rows (1-1,000)","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Rows to skip","schema":{"type":"integer"}},{"name":"format","in":"query","required":false,"description":"json (default) or csv","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"The changes, each with the agency's id, a link to the original and what moved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/compliance/watches":{"get":{"tags":["compliance"],"operationId":"listComplianceWatches","summary":"Your compliance alerts (API key): what each covers, how it's delivered, when it last went out and what it did","responses":{"200":{"description":"Watches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["compliance"],"operationId":"createComplianceWatch","summary":"Set up an alert on one list (API key): JSON {list, name?, zips?, status?, type?, stacked?, kinds?, cadence: daily|weekly, email?, webhook_url?, track?: [item keys]}. Delivered from 15:00 UTC (weekly on Mondays) by email and/or a webhook signed X-SOS-Signature: t=…,v1=HMAC-SHA256(secret, \"t.body\"). Rows past the first 10 in a delivery cost 100 credits per 100; without credits the alert still comes with the counts and nothing is charged. Tracked items close on their own when the agency's data no longer lists them","responses":{"200":{"description":"The watch, and webhook_secret when a webhook was given (shown once)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/compliance/watches/{id}":{"get":{"tags":["compliance"],"operationId":"getComplianceWatch","summary":"One alert","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The watch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["compliance"],"operationId":"deleteComplianceWatch","summary":"Stop an alert and its tracked items","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/compliance/watches/{id}/track":{"post":{"tags":["compliance"],"operationId":"trackComplianceItems","summary":"Track items one by one: JSON {items: [item keys], remove?: true}. Up to 1,000 per watch","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"How many are tracked, and which keys aren't on the list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/store/building-record":{"get":{"tags":["store"],"operationId":"getBuildingRecord","summary":"Permits, code cases and inspections for one address (900 credits or x402)","parameters":[{"name":"address","in":"query","required":true,"description":"Street address with house number","schema":{"type":"string"}},{"name":"zip","in":"query","required":false,"description":"ZIP","schema":{"type":"string"}},{"name":"place","in":"query","required":false,"description":"Place id (default us-ca-los-angeles; see the store catalogue for the list)","schema":{"type":"string"}},{"name":"agree_data_use","in":"query","required":true,"description":"Must be 1","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/risk":{"get":{"tags":["risk"],"operationId":"riskList","summary":"Free: natural-hazard risk for the 30 largest U.S. cities (FEMA National Risk Index by county). Lists cities; format=csv returns every city and hazard","parameters":[{"name":"city","in":"query","required":false,"description":"City id, name or county FIPS: returns one profile","schema":{"type":"string"}},{"name":"fips","in":"query","required":false,"description":"Five-digit county FIPS","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"json or csv","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"Cities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/risk/{id}":{"get":{"tags":["risk"],"operationId":"riskCity","summary":"Free: one city's risk profile: overall FEMA rating and score, each hazard's share of risk, rating, score and expected annual loss; disaster declarations and the official alert sign-up for verified cities","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"City id from /v1/risk, e.g. dallas"}],"responses":{"200":{"description":"Profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/bank":{"get":{"tags":["bank"],"operationId":"bankOverview","summary":"Bank desert watch: what's free, what's paid, the latest build and its sources","responses":{"200":{"description":"Overview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}}}}},"/v1/bank/access":{"get":{"tags":["bank"],"operationId":"bankAccess","summary":"Free: bank and credit union access for a ZIP, county or state (or the US): branches, nearest bank, recent closings, ZIP gaps, top lenders","parameters":[{"name":"zip","in":"query","required":false,"description":"Five-digit ZIP","schema":{"type":"string"}},{"name":"county","in":"query","required":false,"description":"Five-digit county FIPS","schema":{"type":"string"}},{"name":"place","in":"query","required":false,"description":"County or state place id","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"Two-letter state","schema":{"type":"string"}}],"responses":{"200":{"description":"Access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/bank/gaps":{"get":{"tags":["bank"],"operationId":"bankGaps","summary":"ZIPs a closing left with no bank, one bank or a 10+ mile trip. Free: last 30 days, 25 rows. full=1 or CSV: 100 credits (free with a watch)","parameters":[{"name":"state","in":"query","required":false,"description":"Two-letter state","schema":{"type":"string"}},{"name":"alert","in":"query","required":false,"description":"new_desert | lost_last_bank | down_to_one_bank","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"YYYY-MM-DD","schema":{"type":"string","format":"date"}},{"name":"full","in":"query","required":false,"description":"1 = the whole 120-day window (paid)","schema":{"type":"string","enum":["1"]}},{"name":"format","in":"query","required":false,"description":"json or csv","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"Gaps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/bank/lenders":{"get":{"tags":["bank"],"operationId":"bankLenders","summary":"Every bank and credit union with a branch in one county, with size (25 credits; free with a watch)","parameters":[{"name":"county","in":"query","required":true,"description":"Five-digit county FIPS","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"bank | credit_union","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"json or csv","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"Lenders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/bank/events":{"get":{"tags":["bank"],"operationId":"bankEvents","summary":"Branch openings and closings with addresses. Free: last 30 days. Older: 10 credits (free with a watch)","parameters":[{"name":"state","in":"query","required":false,"description":"Two-letter state","schema":{"type":"string"}},{"name":"county","in":"query","required":false,"description":"Five-digit county FIPS","schema":{"type":"string"}},{"name":"zip","in":"query","required":false,"description":"Five-digit ZIP","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"opened | closed","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"YYYY-MM-DD","schema":{"type":"string","format":"date"}},{"name":"format","in":"query","required":false,"description":"json or csv","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/bank/export":{"get":{"tags":["bank"],"operationId":"bankExport","summary":"A whole table as CSV: every county, every ZIP or every bank (2900 credits; free on National)","parameters":[{"name":"table","in":"query","required":false,"description":"county | zip | institutions","schema":{"type":"string","enum":["county","zip","institutions"]}}],"responses":{"200":{"description":"CSV","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/bank/checkout":{"post":{"tags":["bank"],"operationId":"bankCheckout","summary":"Buy a watch (State $99/mo, Regional $299/mo, Closing soon $49/mo, Branch sites $199/mo, National $999/mo) or a report (Market brief $500, Acquisition screen $1,500, Merger impact $750)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product","email","agree_data_use"],"properties":{"product":{"type":"string","description":"Watch or report id","enum":["bank_state_watch","bank_regional_watch","bank_closing_soon","bank_sites","bank_national","bank_market_brief","bank_acquisition_screen","bank_merger_impact"]},"email":{"type":"string","description":"The person who pays"},"states":{"type":"string","description":"Two-letter states, comma-separated (watches)"},"scope":{"type":"string","description":"For reports: the market, deal or target"},"agree_data_use":{"type":"boolean","description":"Must be true"}}}}}},"responses":{"201":{"description":"Checkout started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/Error"}}}},"/v1/bank/orders/{id}":{"get":{"tags":["bank"],"operationId":"bankOrder","summary":"Watch or report order status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"t","in":"query","required":true,"description":"Order token from status_url","schema":{"type":"string"}}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}}}}},"/v1/checkout/claim":{"get":{"tags":["store"],"operationId":"claimKey","summary":"After paying: show a new account's API key once","parameters":[{"name":"session","in":"query","required":true,"description":"Stripe Checkout session id","schema":{"type":"string"}}],"responses":{"201":{"description":"The key, shown once"},"404":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key: sos_live_…"}},"schemas":{"Object":{"type":"object","additionalProperties":true},"Results":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"Source":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"integer"},"record":{"type":"string"},"publisher":{"type":"string"},"page_url":{"type":"string"},"api_url":{"type":"string"},"licence":{"type":"string"},"reuse":{"type":"string","description":"ok | check | link-only | no"},"checked":{"type":"string"},"last_checked_at":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"Payment required: pay with an API key's credits, or x402 v2 (PAYMENT-REQUIRED header; retry with PAYMENT-SIGNATURE)","headers":{"PAYMENT-REQUIRED":{"description":"Base64 x402 v2 PaymentRequired (when x402 is on)","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}}}}}