# REST API overview

URL: https://briq.cloud/docs/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.

```text
https://api.briq.cloud/v1
```

Breaking 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:

```bash
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 `costCentsSoFar` and `sleepsAt`.
* `sleep` is a string with a unit: `"30m"`, `"3h"`, `"7d"`, or `"never"`. A number there is
  refused with the string to send instead.

## Errors

```json
{ "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`](https://api.briq.cloud/v1/openapi.json) describes every endpoint; point any
OpenAPI generator at it for a typed client.