REST API overview

Everything the MCP server and the dashboard do goes through one REST API. The SDK and the CLI are thin clients over it.

Base URL

https://api.briq.run/v1

Versioned in the path. Breaking changes get a new version; additive fields do not.

Authentication

Send an API key as a Bearer token:

curl https://api.briq.run/v1/briqs \
  -H "Authorization: Bearer $BRIQ_API_KEY"

Keys are looked up by prefix and compared in constant time against a SHA-256 hash. Dashboard routes (key minting, team management) use the session instead of a key.

Requests and responses

JSON in, JSON out. Content-Type: application/json.
Field names are camelCase and match the Zod schemas in @briq/core: costCentsSoFar, stopsAt, ttlMinutes.
Money is in euro cents. Sub-cent per-second usage is a float.
Timestamps are ISO 8601 in UTC.
Every response about a briq includes costCentsSoFar and stopsAt.

Errors

{
  "error": {
    "code": "policy_violation",
    "message": "size medium is not allowed for this key (allowed: nano, small)"
  }
}

Code	HTTP	When
`validation`	400	Body or query failed schema validation; `details` carries the issues
`unauthorized`	401	Missing, malformed, expired or revoked key
`forbidden`	403	The key's team cannot access this resource
`policy_violation`	402	The key's policy forbids the request (size, registry, TTL, concurrency)
`quota_exceeded`	402	Daily spend cap or credits exhausted
`not_found`	404	Unknown briq, stack or recipe
`invalid_state`	409	Transition not allowed from the current state
`provider_error`	502	The provider failed; the reconciler will clean up

Streaming

POST /v1/briqs/:id/exec and GET /v1/briqs/:id/logs?follow=true can stream over Server-Sent Events when the request carries Accept: text/event-stream.

Audit

Every authenticated request writes one audit row: key id, action, target, duration and cost delta. Read it back with GET /v1/audit or in the dashboard.

OpenAPI

The spec is generated from the Zod schemas and served at /v1/openapi.json. The TypeScript SDK is generated from it.