getting started

0 get an API key

Free and self-service. One request mints a key; the server shows it to you exactly once, so save it.

curl -X POST https://shinnslist.com/api/keys

Send the key on every call as the x-api-key header (preferred), or ?key= in the query string. No key still works — you fall back to the anonymous tier.

All signals are available on every tier — quota is the gate. Key issuance is rate-limited to 3 keys per ip per hour.

1 run your first parcel query

Pick any parcel by address, lat/lng, or locality and ask the engine for intel. A lat/lng pair is the most predictable first call:

curl -H "x-api-key: YOUR_KEY" \
  "https://shinnslist.com/api/intel?q=37.5407,-77.4360"

Every response uses the same envelope. result holds the signal's fields — or is empty when the signal can't be computed. unavailable names the exact reason when there's no free source; evidence cites the named public dataset behind each fact. Nothing is fabricated:

{
  "signal_id": "best_value_number",
  "catalog_number": 1,
  "title": "Best Value Number",
  "status": "pending",
  "result": { /* signal-specific fields — null when pending */ },
  "evidence": [ { "fact": "…", "source": "named public dataset", "retrieved": "2026-09-27" } ],
  "unavailable": [ /* exact reasons when degraded/pending, else omitted */ ],
  "confidence": "high | medium | low"
}

Coverage today is virginia parcels; a query outside virginia returns -32005 and says so. The full signal catalog, statuses, and per-signal curl examples live in the api reference.

2 run your first chat search

Prefer plain language over curl? The chat is the same engine behind a conversation:

1. Open chat.
2. Type what you want, the way you'd say it — for example "assumable mortgages under 4% near richmond".
3. The bot parses the query, ranks real parcels on the spot, and shows its reasoning next to the results. If it can't answer from the data it has, it says so rather than guessing.

For agent builders: the same capability is available programmatically over MCP at /api/mcp — see the api reference quickstart.

3 build your first list

Lists turn queries into repeatable hunts. One honest note up front: the list builder's preview runs against a demo parcel universe in your browser — its match counts are scaled estimates, tagged demo on the page, not real coverage. The real engine queries live under /api/intel and chat.

1. Open lists to see and manage your saved lists.
2. Open the list builder to stack filters — signals, zips — and preview which parcels the demo universe matches.
3. Save the list. The match-quality panel shows per-list signal coverage and freshness breakdown — computed from demo fields for now, honest about what they are.