REST API

Limits and good practice

Quotas, timeouts and long-running calls in the Brunel REST API, plus practical advice for CI pipelines and agents.

Quotas

API calls count against your plan exactly like the app: tracked projects, analyses per month and AI actions per month. See Plans and limits. When a quota is used up, calls answer upgrade_required (402) until the next month or an upgrade.

Long calls

Endpoint	Typical duration
`POST /v1/projects` (analysis)	5 to 60 seconds, depending on the repository
`POST /v1/projects/{id}/design`	up to about a minute with AI reasoning, seconds with the deterministic architect
`POST /v1/projects/{id}/messages`	seconds to about half a minute
Everything else	well under a second

These calls wait for the result instead of returning a job id. Set your client timeout to at least 120 seconds, and do not retry a call that is still running.

Good practice

Reuse projects. Analyze a repository once, then design and refine the same conversationId; re-analysis is only needed when the code changed.
One key per program, read-only when it only reads.
Log x-request-id with every call you make.
Handle errors by code and back off on 5xx.
Prefer tracking over polling: Real-time tracking re-analyzes on push and sends signed webhooks.