Public API Reference

Base URL

All API endpoints are at:

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

Authentication

Every request requires an API key in the Authorization header:

Authorization: Bearer brk_your_key_here

Create API keys from Dashboard → API. See API Keys for details.

Endpoints

GET /api/v1/agent/status

Returns your agent’s current status, product version, and metadata.

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-03-25T14:30:00.000Z",
    "product": "openclaw",
    "subdomain": "gateway-abc",
    "openclawVersion": "2026.3.7",
    "createdAt": "2026-01-15T00:00:00.000Z"
  }
}

If no agent is provisioned, the response is { "agent": null, "message": "No agent provisioned" }.

Status values: running, stopped, pending, stopping

Sleep reasons: When your agent is auto-slept due to inactivity, sleepReason indicates why (e.g., "idle"). It clears automatically when you start the agent.

POST /api/v1/agent/start

Starts your agent (scales to 1 replica). Returns immediately — the agent may take 30-60 seconds to boot.

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

Response:

{
  "message": "Agent starting",
  "status": "pending"
}

If the agent is already running:

{
  "message": "Agent is already running",
  "status": "running"
}

POST /api/v1/agent/stop

Stops your agent (scales to 0 replicas). Your data and configuration persist.

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

Response:

{
  "message": "Agent stopping",
  "status": "stopping"
}

If the agent is already stopped:

{
  "message": "Agent is already stopped",
  "status": "stopped"
}

GET /api/v1/billing

Returns your current plan and subscription information.

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

Response:

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

When a Stripe subscription is active, stripeCustomerId returns "configured" and stripeSubscriptionId returns "active" (actual IDs are never exposed).

Error Responses

All errors return JSON with an error field:

{ "error": "Invalid or revoked API key" }

Server errors (5xx) include an errorId for support:

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

Common status codes:

• 401 — Missing or invalid API key
• 404 — No agent found for your account
• 500 — Internal server error (include the errorId when contacting support)

Integration Examples

CI/CD: Start Agent Before Tests

# GitHub Actions step
- name: Start BrainRoad agent
  run: |
    curl -sf -X POST https://app.brainroad.com/api/v1/agent/start \
      -H "Authorization: Bearer ${{ secrets.BRAINROAD_API_KEY }}"

    # Wait for agent to be ready
    for i in $(seq 1 30); do
      STATUS=$(curl -sf https://app.brainroad.com/api/v1/agent/status \
        -H "Authorization: Bearer ${{ secrets.BRAINROAD_API_KEY }}" \
        | jq -r '.agent.status')
      [ "$STATUS" = "running" ] && break
      sleep 2
    done

Monitoring: Check Agent Health

import requests

resp = requests.get(
    "https://app.brainroad.com/api/v1/agent/status",
    headers={"Authorization": "Bearer brk_your_key_here"},
)
agent = resp.json().get("agent")

if agent and agent["status"] != "running":
    print(f"Agent is {agent['status']}, restarting...")
    requests.post(
        "https://app.brainroad.com/api/v1/agent/start",
        headers={"Authorization": "Bearer brk_your_key_here"},
    )