Ask the Agent — Developer Docs
Agent questions with model choice, citations and recoverable turn history.
How do I ask the project agent a question?
POST /v1/projects/{project_id}/messages runs the same ChatAgent the app uses. Send wait: false to receive a pollable job handle, or use the default wait: true for a synchronous answer with citations, tool usage and generated artifacts.
Limits and behavior:
- Rate limit: 2/min per key, with a concurrency limit of 2 in-flight questions.
- Send an
Idempotency-Keyheader — a retried request returns the original turn instead of re-running (and re-billing) the agent. - Before the project is ready you get
409withbootstrap_not_ready; when parcels still need zoning confirmation you get409withzoning_verification_required. PollGET /v1/projects/{project_id}and retry.
Model selection: Read GET /v1/models for the same approved models, Auto default and estimated credit rates the app offers (requires agent:ask; no inference or charge). Pass an exact returned model_id with your message, or omit it, send null, or send auto to use Auto. Each API request defaults to Auto on its own.
A rejected, unavailable or disabled explicit selection fails before the turn starts. The answering model can be selected; report generation, classifiers and other tools retain their own task-specific models. Finished responses, and a turn read back by id, expose model_selection with requested/resolved IDs and observed served identity when available.
Reading turns back:
| Endpoint | What it returns |
|---|---|
GET /v1/projects/{project_id}/messages/{turn_id} | One prior turn (question, answer, citations, artifacts) |
GET /v1/projects/{project_id}/messages | Turn list for the project - API-surface turns only, not in-app chat history; data a page at a time (limit, cursor, next_cursor) plus running_turns |