Public API Reference

Base URL and authentication

All REST endpoints live under:

https://app.brainroad.com/api/v1/

Every request needs an API key with the right scope:

Authorization: Bearer brk_your_key_here

Create keys from Dashboard → API. See API Keys for scopes. Limit: 120 requests per minute per key.

Helper status and lifecycle

GET /api/v1/agent/status

Scope: agent:read. Returns your helper’s current status. If you run both OpenClaw and Hermes, add ?product=openclaw or ?product=hermes; without it, OpenClaw is picked.

curl https://app.brainroad.com/api/v1/agent/status \
  -H "Authorization: Bearer brk_your_key_here"

Response:

{
  "agent": {
    "id": "abc123",
    "status": "running",
    "sleepReason": null,
    "lastActivityAt": "2026-07-20T14:30:00.000Z",
    "product": "openclaw",
    "subdomain": "gateway-abc",
    "openclawVersion": "2026.7.1",
    "createdAt": "2026-06-15T00:00:00.000Z"
  }
}

With no helper provisioned: { "agent": null, "message": "No agent provisioned" }.

POST /api/v1/agent/start and /agent/stop

Scope: agent:write. Start additionally requires an active trial or subscription. Both accept an optional {"product": "openclaw" | "hermes"} body. Start returns immediately; booting usually takes under a minute. Stop keeps all data and configuration.

The plural /agents surface

For scripts that manage helpers explicitly:

Endpoint	Scope	Notes
GET /api/v1/agents	agent:read	List your helpers
GET /api/v1/agents/:agentId	agent:read	One helper’s detail
POST /api/v1/agents/provision	agent:provision	Also requires an active subscription. May return 202 with status: "pending", which means provisioning was queued for automatic retry; do not re-submit
POST /api/v1/agents/:agentId/start / stop / update	agent:write	Update requires a running helper
DELETE /api/v1/agents/:agentId	agent:provision	Removes the helper

Proposing work for review

External tools can stage drafts in your Inbox, but never approve or send anything. Cards created over the API always land as pending for you to review in the dashboard.

POST /api/v1/triage/:agentId/cards

Scope: triage:propose. Creates a review card. Required fields: trigger and title; useful optional fields include summary, proposedAction, proposedActionKind, proposedActionPayload, and dedupeKey (deduplicated per key, so a safe retry returns the same card).

GET /api/v1/triage

Scope: triage:read. Lists pending cards across your helpers. Optional ?agentId= and ?limit= (max 200).

There is no approval endpoint. Approving, editing, or declining a card happens in the dashboard Inbox only.

Connector trust

Endpoint	Notes
GET /api/v1/agents/:agentId/connector-trust	Read per-connector trust settings
PUT /api/v1/agents/:agentId/connector-trust/:connectorKey	Set a registered connector to allow, ask, or block, with an optional daily budget

Connectors themselves are managed from the Inbox settings in the dashboard; this API adjusts trust for connectors that are already registered.

Billing (read-only)

GET /api/v1/billing

Scope: billing:read.

{
  "plan": "free",
  "trialStartedAt": "2026-07-01T00:00:00.000Z",
  "trialEndsAt": "2026-07-31T00:00:00.000Z",
  "stripeCustomerId": null,
  "stripeSubscriptionId": null
}

When a payment account is linked, stripeCustomerId returns "configured", and stripeSubscriptionId reports the subscription status ("active", "trialing", "past_due", "canceled") instead of a real ID. Upgrading, checkout, and the billing portal are dashboard-only; there is no way to change billing over an API key.

Events (SSE)

GET /api/v1/events streams live activity. See Event Streaming.

OpenAI-compatible chat API

Separate from /api/v1/, BrainRoad serves an OpenAI-compatible surface at:

https://app.brainroad.com/v1

• POST /v1/chat/completions (scope chat:write) sends a message to your helper and returns its reply. Works with any OpenAI SDK by setting base_url to https://app.brainroad.com and the API key to your brk_ key.
• GET /v1/models lists your helpers as models.
• The model field selects which helper answers ("agent-<id>"), not which LLM. Your helper’s configured model does the work; there is no per-call model override.
• Requires an active trial or subscription.
• Errors use OpenAI’s nested {"error": {"message", "type", "code", "param"}} shape.
• Limits: 20 requests/min per key for chat completions, 60/min for the model list.

from openai import OpenAI

client = OpenAI(base_url="https://app.brainroad.com", api_key="brk_your_key_here")
reply = client.chat.completions.create(
    model="agent-abc123",
    messages=[{"role": "user", "content": "Summarize today's new leads."}],
)
print(reply.choices[0].message.content)

Errors

/api/v1/ errors return flat JSON with an error field; 5xx responses include an errorId for support:

{ "error": "Failed to start agent", "errorId": "err_a1b2c3d4" }

Common codes: 401 (missing or invalid key), 403 (key lacks the required scope), 404 (no helper found), 429 (rate limit), 500 (include the errorId when contacting support).