BrainRoad REST API: Control Your AI Agent Programmatically

There are two ways to use an AI agent. The first: you open a dashboard, type what you need, and wait. The second: your code calls an endpoint at 2 AM, the agent runs, and you wake up to finished output. The gap between those two experiences is a REST API.

Most people start in the dashboard. That’s fine — it’s how you learn what your agent can do. But at some point, you realize the real power isn’t in the UI. It’s in making the agent a component in a larger system. Something your CI pipeline can trigger. Something your CRM can hand off to. Something that runs without you.

BrainRoad is built on OpenClaw — which had 154,500 GitHub stars and 2 million weekly weekly visitors as of early 2026, making it the dominant open-source AI agent platform. OpenClaw exposes a RESTful interface. That’s the good news. The less-good news? Default installations ship with the API bound to every network interface and no authentication in front of it. I’ll get to that — and it matters more than the integration guide — but first, let’s cover what you’re actually working with.

What a REST API Actually Gives You

If you’ve worked with REST APIs before, this will feel familiar. If you haven’t: a REST API is just a set of URLs your code can call to make things happen. You send a request. The server responds. Your agent acts.

For an AI agent platform, that translates to a few concrete capabilities:

This is the same pattern used by production AI agent platforms across the industry. The OpenHands Cloud API, launched in May 2025, works the same way: RESTful endpoints, Bearer token auth, task payloads that include a repository URL, and the agent handles the rest. The principles transfer directly.

For anyone building a personal AI assistant that goes beyond the chat window, this is the architecture worth understanding. The AI agent platform layer is what sits between your workflow and the model — and the API is how you reach it.

BrainRoad API Keys: Format, Generation, and Security

Before you write your first request, you need a key. BrainRoad API keys use the prefix brk_ followed by 64 hex characters — a total of 68 characters. Example shape: brk_a1b2c3d4e5f6... (the rest is random, never shown again after creation).

To generate one:

1. Open the BrainRoad dashboard
2. Go to Settings → API Keys
3. Click New API Key, give it a descriptive name (e.g. ci-pipeline or monitoring)
4. Copy the key immediately — BrainRoad stores only the hash. You cannot retrieve the raw key after this screen.

You can have up to 10 active keys per account. Revoke keys you no longer need. Each key is linked to your account and scopes to your agent — one API call, one gateway.

Pass the key as a Bearer token on every request:

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

The BrainRoad Public API: What You Can Do

The API lives at https://brainroad.com/api/v1/. All endpoints require your brk_ key in the Authorization header. All responses are JSON.

Check your agent’s status:

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

Response:

{
  "agent": {
    "id": "gw_abc123",
    "status": "running",
    "sleepReason": null,
    "lastActivityAt": "2026-03-20T07:45:00.000Z",
    "product": "starter",
    "subdomain": "gateway-abc123",
    "openclawVersion": "2.1.0",
    "createdAt": "2026-02-01T12:00:00.000Z"
  }
}

Status values: running, stopped, pending, sleeping. If sleepReason is set, the agent was auto-slept by the idle sweeper — it will wake automatically on next activity or you can wake it via the API.

Wake a sleeping or stopped agent:

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

Response: { "message": "Agent starting", "status": "pending" }. The agent takes ~30 seconds to become fully operational. Poll /agent/status until status is running.

Stop a running agent:

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

Useful for cost control — a stopped agent doesn’t consume compute. The idle sweeper handles this automatically for inactive agents, but you can also trigger it from your own workflows.

Check your billing status:

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

Returns your plan, trial dates, and whether Stripe billing is active. Useful for monitoring dashboards that need to surface subscription state alongside agent health.

Stream live agent activity (SSE):

curl -H "Authorization: Bearer brk_your_key_here" \
  -H "Accept: text/event-stream" \
  https://brainroad.com/api/v1/events

This opens a Server-Sent Events stream. Every action your agent takes — file edits, tool calls, messages sent — arrives as an activity event. Filter by category with ?category=tool_call. The stream sends a keepalive comment every 30 seconds so your connection stays alive through idle periods.

Full API reference:

Endpoint	Method	What it does
/api/v1/agent/status	GET	Agent state, sleep reason, version, subdomain
/api/v1/agent/start	POST	Wake a stopped or sleeping agent
/api/v1/agent/stop	POST	Stop a running agent
/api/v1/billing	GET	Plan, trial dates, subscription status
/api/v1/events	GET (SSE)	Real-time activity stream

This pattern — GET for state, POST for action, SSE for streaming — is consistent across modern agent platforms. Moveo.AI’s REST API exposes similar patterns with capability gating. The principles transfer regardless of platform.

The Security Gap Nobody Mentions in the Quickstart

Here’s what I promised to get back to.

A default OpenClaw installation — the kind you get from a one-liner install script — exposes port 3000 with no authentication, stores credentials in a plaintext file, and binds the gateway to every network interface on the machine. That’s not a theoretical risk. As of the time we last checked, there were approximately 42,000 exposed OpenClaw installations accessible on the public internet.

Think about what that means in the context of a REST API. You’ve just built a clean programmatic interface to your agent. Anyone who can reach port 3000 can use it — trigger tasks, read your agent’s configuration, potentially interact with any tool the agent has access to. The API is powerful precisely because it gives programmatic control. An unauthenticated API gives that control to everyone.

The fix is not complicated. But it does take longer than most quickstarts suggest. We’ve run both versions: the one-liner install was up in four minutes. A production-ready setup — with egress controls, audit logging, encrypted credentials, and a reverse proxy in front — took closer to three days. That’s the real number.

This is the counterintuitive part of building on top of AI agent APIs: the integration code is the easy part. A few HTTP calls, some JSON parsing, done in an afternoon. The infrastructure hardening is where the real work lives — and where most tutorials quietly stop before reaching.

We wrote the full breakdown in How to Set Up OpenClaw: The Easy Way vs The Hard Way if you want the specific configs. The short version is below.

Locking It Down Before You Build On It

Before you write a single line of integration code, get this infrastructure baseline in place:

1. Reverse proxy in front of the API port. nginx or Caddy. Terminate TLS here. Never expose port 3000 directly.
2. Bind the API to localhost only. Change the default network binding so the agent isn’t listening on every interface — only the one your proxy can reach.
3. Replace plaintext credential storage. Move credentials to environment variables or a secrets manager. A .env file with tight permissions is the floor, not the ceiling.
4. Implement Bearer token auth at the proxy layer. Even if the underlying platform supports it natively, enforce it at the proxy too. Defense in depth.
5. Enable audit logging. Every API call should generate a log entry: timestamp, endpoint, API key ID (not the key itself), response code. You need this when something breaks.
6. Set up egress controls. Decide which external domains your agent is allowed to reach. An agent that can call any URL is an agent that can be pointed at anything.

BrainRoad handles this layer automatically — isolated containers, encrypted credential storage, proxy configuration included. The reason we built it that way is exactly this: we watched too many self-hosted setups skip the hardening and pay for it later. If you’re managing your own infrastructure, the list above is the minimum. If you’d rather not manage it, that’s what a hosted personal AI assistant platform is for.

Where REST API Integration Actually Breaks

The API itself is rarely the failure point. What breaks is usually around it.

• Token expiry with no rotation logic. API keys expire or get rotated, your integration doesn’t handle it gracefully, and tasks start silently failing at 3 AM with no alert.
• No idempotency on task triggers. If your code retries a failed request and the agent runs the same task twice, you get duplicate outputs, duplicate actions, or both. Design your task submissions to be idempotent.
• Context payload size limits. Passing a repository URL that points to a 2GB codebase in a request payload will fail, time out, or behave unpredictably. Know your limits before you hit them.
• Polling without backoff. If you’re polling a status endpoint to check when a long-running task finishes, implement exponential backoff. Aggressive polling hammers the API and can get your key rate-limited.
• Assuming synchronous behavior. Most agent tasks are asynchronous — you submit, get a task ID back, then poll or wait for a webhook. Code that expects an immediate result will break on any task that takes more than a few seconds.
• State drift between agent and caller. If your integration caches agent configuration and the agent gets updated, your local state is stale. Always re-fetch state before making decisions that depend on it.

The Llama Stack Responses API, used in combination with orchestration frameworks like LangGraph, solves some of this by automating tool calling while maintaining control over conversation state. The principle applies here: separate the ‘trigger the agent’ layer from the ‘manage the state’ layer. They have different failure modes and should be handled independently.

How to Know the Integration Is Actually Working

Smoke testing isn’t enough. Here’s what a healthy API integration looks like in practice:

Beacon says: a well-lit API is the difference between guessing and knowing exactly what your AI is doing.

• Every task submission returns a task ID — not a success message, not a 200 OK with no body. A task ID means you have something to track.
• Status polling returns consistent state transitions. A task should move from pending → running → completed (or failed). If you see it stuck in running for more than your expected max duration, something is wrong.
• Audit logs show expected call patterns. If you triggered 10 tasks, you should see 10 log entries. Gaps mean requests aren’t reaching the API layer — check your proxy config.
• Structured JSON output parses without errors. Your integration should have a schema for expected output. If parsing fails, log the raw response and alert — don’t silently swallow the error.
• Auth errors surface immediately. A 401 or 403 response should trigger an alert, not a silent retry. Unexpected auth failures mean a key was rotated, revoked, or something changed in your permission model.
• The agent’s GET endpoint returns expected configuration. Before running any critical task, query the agent’s configuration endpoint and verify it matches what you expect. Don’t assume the agent is in the state you left it.

Your Monday Morning API Integration Checklist

If you’re starting this week, here’s the sequence that won’t bite you later:

1. Harden the infrastructure first. Reverse proxy, localhost binding, encrypted credentials, audit logging. Budget 1-3 days for this if you’re self-hosting. Zero days if you’re on BrainRoad — it’s handled.
2. Generate scoped API keys. Create at least two: one read-only (for monitoring and status queries), one execution key (for triggering tasks). Store both in your secrets manager, not in source code.
3. Smoke test auth before anything else. Call GET /api/v1/agent/status with your key. You should get a 200 with agent JSON. If you get a 401 or the call times out, your key is wrong or your network can’t reach brainroad.com — fix this before anything else.
4. Test lifecycle control. Stop your agent via POST /api/v1/agent/stop, verify /agent/status returns stopped, then start it again and confirm pending → running. This proves your key has write access and the gateway responds correctly.
5. Implement error handling before you implement features. 401 handling, retry logic with exponential backoff (start at 1 second, cap at 30 seconds), and a dead-letter queue for failed tasks. This takes 2-4 hours and saves days later.
6. Set an alert on any 5xx response from the API. Not a log entry — an alert. Your agent going down silently is worse than knowing it went down.
7. If you’re handling sensitive data, add egress controls within 24 hours of first production use. Don’t let ‘we’ll do it later’ become ‘we never did it.’

The BrainRoad Console Guide covers the dashboard side of this — useful for verifying what you’re seeing in API responses matches what the agent’s UI shows. Worth cross-referencing when you’re debugging state issues.

The teams that get this right early don’t just have a working integration — they have a foundation that compounds. Every workflow you automate on top of it gets cheaper to build. Every new tool you connect takes hours, not days. The teams that skip the hardening step? They rebuild from scratch six months later, usually after an incident.

The AI assistant market is growing fast — projected from $3.35 billion in 2025 to $21.11 billion by 2030, a 44.5% compound annual growth rate — and most of that growth isn’t in better chat interfaces. It’s in agents that integrate into existing systems via exactly this kind of programmatic access. The REST API layer is how agents stop being tools you visit and start being infrastructure you rely on.

What This Means for Your Build Strategy

• REST APIs for AI agents follow standard patterns — Bearer token auth, GET for state, POST for action — and integrate with any language that can make HTTP requests.
• The integration code is not the hard part. Default OpenClaw deployments expose port 3000 with no authentication and plaintext credentials — hardening takes 1-3 days of real work, not 15 minutes.
• As of early 2026, roughly 42,000 OpenClaw installations were publicly accessible on the internet with no authentication. Don’t be one of them.
• Scope your API keys: separate read-only from execution keys. Build idempotency and exponential backoff into your integration before you build features.
• Production-ready agent API integration requires a reverse proxy, encrypted credential storage, audit logging, and egress controls. Budget accordingly — or use a managed platform that handles it for you.

Frequently Asked Questions

What authentication method does the BrainRoad REST API use?

Bearer token authentication. You pass your API key in the Authorization header of every request. Generate separate keys for read operations and execution operations — if a read key leaks, your agent can’t be commanded to act on it.

Can I trigger my AI agent from an external tool like a CRM or CI pipeline?

Yes. Any tool that can make an HTTP POST request can trigger your agent. You send a task payload with your instruction and any context (like a repository URL or document reference), and the agent runs asynchronously. You get a task ID back to poll for results.

Why is the default OpenClaw installation a security risk for API access?

A default install binds to all network interfaces, runs on port 3000 with no authentication, and stores credentials in a plaintext file. That means anyone who can reach that port has full API access. Run a reverse proxy in front, bind to localhost only, and use encrypted credential storage before you expose any API functionality.

What's the difference between self-hosting the OpenClaw API and using BrainRoad?

Self-hosting gives you full control and takes 1-3 days to configure securely. BrainRoad runs the same OpenClaw infrastructure with hardening already applied — isolated containers, encrypted credentials, proxy configuration included. The tradeoff is control vs. time. Most users who don’t need custom infrastructure configs are better served by managed hosting.

How do I handle long-running agent tasks via the API?

Agent tasks are asynchronous. Your POST request returns a task ID immediately. Poll the status endpoint with exponential backoff (start at 1 second, cap at 30 seconds) until the status reaches completed or failed. Never assume synchronous behavior — tasks that involve reading large codebases or calling multiple tools can take minutes.

Sources

• OpenHands Cloud API Launch — openhands.dev
• Moveo.AI REST API Documentation — docs.moveo.ai
• Embabel Framework: Build a REST API Based AI Agent — bootcamptoprod.com
• Automate AI Agents with the Responses API in Llama Stack — developers.redhat.com
• OpenClaw Setup: Easy Way vs Hard Way — brainroad.com
• 5 OpenClaw Use Cases That Change How You Work — brainroad.com
• One AI Assistant for Email, Calendar & Every App — brainroad.com

What BrainRoad Exposes Beyond REST Today

If REST is your first touchpoint, the current BrainRoad product already includes the adjacent surfaces most teams end up needing next:

• API keys plus the documented public API for lifecycle and billing operations.
• A hosted MCP endpoint when Claude Code, Cursor, or another MCP client should call the same agent directly.
• Two realtime interfaces: SSE for external monitoring and WebSocket RPC for lower-level control.
• AI Company when the work stops being “trigger one agent” and starts being “coordinate multiple specialists.”

That is the practical path from one-off API calls to a broader operating layer. You do not have to switch products to get there.