Skip to main content
POST
Ask Site
Answers a question about a site registered with POST /v1/sites. One model call over the persisted dossier — it never re-fetches, because the sieve already ran at registration.
question is capped at 2,000 characters. The answer comes back with citations, the same as /v1/ask.

Why this exists

Ask ten questions about one parcel through /v1/ask and you pay for ten planner runs and ten rounds of fetching over the same ground. Through a site, you pay for the screen once and then ten cheap reads against it. That maps onto how diligence actually goes: a site gets picked up, gets interrogated from several angles over days, and gets dropped or advanced. The expensive part should happen once, at the front.

Timing

If the site is still building, you get a 202 — poll GET /v1/sites/{site_id} until it reports ready. Registration runs a real screen across the polygon and takes minutes, not seconds. 10 credits per question.

Failures

An incomplete answer is stochastic rather than a property of the question, so a retry usually succeeds. It is never returned as a 200 with an empty answer — if you have code branching on an empty answer string, you can drop it.

Scope

The dossier is a snapshot from built_at. It does not refresh itself. For a site you are tracking over months, re-register the polygon to rebuild — same geometry, same site_id.

Body

application/json
site_id
string
required
Required string length: 4 - 64
question
string
required
Required string length: 1 - 2000

Response

Successful Response