REST API overview
Base URL, authentication, errors and conventions.
The MCP server and the dashboard both use this API. Call it from scripts, CI or anything that speaks HTTP.
https://api.briq.cloud/v1Breaking changes get a new version in the path; new fields do not.
Authentication
Send an API key, created on the dashboard's Agents page, as a Bearer token:
curl https://api.briq.cloud/v1/briqs -H "Authorization: Bearer $BRIQ_API_KEY"Access tokens of signed-in MCP clients work too, under the policy approved for that client. Account and team routes use the dashboard session.
Conventions
- JSON in and out, camelCase field names (
costCentsSoFar,sleepsAt). - Money is in euro cents, with decimals for sub-cent amounts.
- Timestamps are ISO 8601, UTC.
- Every response about a briq includes
costCentsSoFarandsleepsAt. sleepis a string with a unit:"30m","3h","7d", or"never". A number there is refused with the string to send instead.
Errors
{ "error": { "code": "policy_violation", "message": "size medium not allowed by key policy" } }Every response carries an x-request-id header, and an error repeats it as requestId. Send
your own x-request-id and it is kept. Quote it when you ask us about a call.
| Code | HTTP | When |
|---|---|---|
validation | 400 | Invalid body or query; details lists the issues |
unauthorized | 401 | Missing, expired or revoked credentials |
forbidden | 403 | Not allowed for this credential or plan |
policy_violation | 402 | The agent's policy forbids it (size, registry, sleep) |
quota_exceeded | 402 | Concurrency limit or daily cap reached |
quota_exceeded | 429 | Rate limit; see retry-after |
payment_required | 402 | The team is out of credits |
not_found | 404 | Unknown briq, stack or recipe |
invalid_state | 409 | Not possible in the briq's current state |
provider_error | 502 | Infrastructure failure |
Rate limits: 300 requests, 30 creations and 120 execs per minute per credential.
Audit
Every authenticated call writes an audit row: credential, action, target, duration, and the
client (via, agentName, agentVersion, userAgent). Files, and an exec's stdin, are recorded
by size, never their content; env vars by name, never their value; and passwords in a command
(--password=…, PGPASSWORD=…, a URL's password) are masked. Read it with GET /v1/audit
(?agent=claude-code, ?key=) or on the dashboard.
OpenAPI
/v1/openapi.json describes every endpoint; point any
OpenAPI generator at it for a typed client.