# REST reference

URL: https://briq.cloud/docs/api/reference

> Every endpoint an agent uses under /v1.

The full schemas are in [`/v1/openapi.json`](https://api.briq.cloud/v1/openapi.json). This page is
the map.

## Briqs

| Method   | Path                               | Notes                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST`   | `/v1/briqs`                        | `{ recipe, params?, name?, sleep? }` or `{ spec }` ([spec](https://briq.cloud/docs/concepts/briq#a-briq-spec)), plus `stack` and `expose` (`"public"` or `"private"`: the URL comes back as `outputs.URL`). Waits until ready, up to `waitTimeoutMs` (120000), unless `wait: false`        |
| `GET`    | `/v1/briqs?stack=&all=`            | List with state and cost; `all=true` includes destroyed briqs                                                                                                                                                                                                            |
| `GET`    | `/v1/briqs/:id`                    | One briq: cost, `sleep` and `sleepsAt`, endpoints, env (secrets masked), `stoppedReason`, `lastExit`, `files` (path and bytes)                                                                                                                                           |
| `POST`   | `/v1/briqs/:id/exec`               | `{ cmd, timeoutMs?, stdin? }` → `{ exitCode, stdout, stderr }`. `cmd` is an argv, run without a shell: `["sh", "-c", "…"]` for pipes or `$VARS`                                                                                                                          |
| `GET`    | `/v1/briqs/:id/logs?since=&limit=` | Log lines and a `next` cursor                                                                                                                                                                                                                                            |
| `POST`   | `/v1/briqs/:id/files`              | `{ path, contentBase64 }`, up to 1 MB; larger is a 400 `validation`, and so is base64 cut short (line breaks are fine) → `{ path, bytes, sha256, verified }`: `verified` when the briq computed the same SHA-256 from its disk. A `warning` when the path is a boot file |
| `PUT`    | `/v1/briqs/:id/files?path=`        | The same, with the raw bytes as the body: `curl -X PUT --data-binary @server.py`; the same answer                                                                                                                                                                        |
| `GET`    | `/v1/briqs/:id/files?path=`        | `{ path, contentBase64 }`, up to 1 MB; larger is a 400 `validation`                                                                                                                                                                                                      |
| `POST`   | `/v1/briqs/:id/expose`             | `{ port, mode?, rotate? }` → `{ url, mode, port, warning? }`. One URL per briq: another port moves it and restarts the machine. See [Expose](https://briq.cloud/docs/guides/expose-a-preview-url)                                                                                          |
| `POST`   | `/v1/briqs/:id/fork`               | `{ name?, stack?, sleep? }`. See [Forks](https://briq.cloud/docs/concepts/fork)                                                                                                                                                                                                            |
| `POST`   | `/v1/briqs/:id/stop`               | Keeps the disk                                                                                                                                                                                                                                                           |
| `POST`   | `/v1/briqs/:id/start`              | Starts a briq stopped by `/stop` or by its own exit. A sleeping briq wakes on its next use without it, and so does one stopped by a limit once the limit has cleared                                                                                                     |
| `POST`   | `/v1/briqs/:id/sleep`              | `{ sleep, stack? }`: `"30m"`, `"3h"`, `"7d"` or `"never"`, a string. `stack: true` for every briq of its stack → `{ briqs }`. See [Sleep](https://briq.cloud/docs/concepts/lifecycle-and-sleep#sleep)                                                                                      |
| `DELETE` | `/v1/briqs/:id`                    | Destroy                                                                                                                                                                                                                                                                  |

## Stacks

| Method | Path                  | Notes                                                        |
| ------ | --------------------- | ------------------------------------------------------------ |
| `GET`  | `/v1/stacks`          |                                                              |
| `POST` | `/v1/stacks`          | `{ name }`. `POST /v1/briqs` also creates the stack it names |
| `GET`  | `/v1/stacks/:id`      | The stack and its briqs                                      |
| `POST` | `/v1/stacks/:id/fork` | `{ into?, sleep? }`                                          |

## Recipes and pricing

| Method | Path                | Notes                                                                       |
| ------ | ------------------- | --------------------------------------------------------------------------- |
| `GET`  | `/v1/recipes`       | Every recipe: name, title, description, tags                                |
| `GET`  | `/v1/recipes/:name` | One recipe: every parameter (type, default, description), outputs and briqs |
| `GET`  | `/v1/pricing`       | Sizes and prices                                                            |

## Agents, quota and audit

| Method            | Path                             | Notes                                                   |
| ----------------- | -------------------------------- | ------------------------------------------------------- |
| `GET`             | `/v1/quota`                      | What this credential may still spend and run            |
| `GET`             | `/v1/audit?limit=&key=&agent=`   | The team's audit events                                 |
| `GET`             | `/v1/usage?days=`                | The team's usage per day (default 14 days)              |
| `GET`             | `/v1/agents`                     | Keys and connected clients                              |
| `GET`, `POST`     | `/v1/keys`                       | List or create keys. Creating needs a dashboard session |
| `PATCH`, `DELETE` | `/v1/keys/:id`, `/v1/agents/:id` | Edit a policy or revoke. Session only                   |

## Support

| Method | Path          | Notes                                                                                                                                                                                                                          |
| ------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST` | `/v1/support` | `{ topic: "question" \| "bug" \| "idea", message }` emails the briq team; the answer goes to the account's address (with a key or an agent's token: to the person who connected it, or the team's owner). Five per ten minutes |

## Example

```bash
curl -X POST https://api.briq.cloud/v1/briqs \
  -H "Authorization: Bearer $BRIQ_API_KEY" -H "Content-Type: application/json" \
  -d '{ "recipe": "postgres", "params": { "version": "16" } }'
```

```json
{
  "briqs": [
    {
      "id": "bq_7kq2m9x1p4ab",
      "name": "db",
      "image": "postgres:16",
      "size": "small",
      "state": "running",
      "internalHost": "…internal",
      "endpoints": [],
      "sleep": "1h",
      "sleepsAt": "2026-09-18T17:41:12Z",
      "costCentsSoFar": 0.058,
      "…": "…"
    }
  ],
  "outputs": { "DATABASE_URL": "postgres://postgres:…@…internal:5432/app" },
  "recipe": "postgres",
  "costLine": "cost so far … · sleeps at 17:41 UTC unless used"
}
```

A recipe can start several briqs, so `briqs` is a list and `outputs` belongs to the run. Destroy
each id with `DELETE /v1/briqs/:id`.