Agent API
Agent API
The Agent API lets your own software do what you do in Chats: find your agents, start a chat, send a message, and read or stream the reply. Use it to put an agent behind your product, wire one into an internal tool, or script work you'd otherwise type by hand.
Every request goes to:
https://api.betterclaw.io
Requests and responses are JSON, except message uploads with files, which use
multipart/form-data. There is no version prefix in the path.
How API keys work
You generate keys on the Agents page: choose Agents under Workspace settings in the
sidebar, then open the API keys tab (or go straight to /agents?tab=api-keys in the app).
Every key is:
- Bound to one workspace. It can only see and act in the workspace it was generated in.
- Optionally pinned to one agent. A pinned key can only start chats with, and open chats of, that agent. Leave it set to Any agent to use every agent in the workspace.
- Acting as the person who generated it. A key is a personal access token for the workspace admin who created it, not a separate service account. Chats it starts are theirs, and are visible to the rest of the workspace like any other chat. If that person leaves the workspace, the key stops working.
- Limited to the permissions you chose.
Only workspace owners and admins can generate or revoke keys. Members can see which keys exist and when they were last used, but never the secret itself.
Permissions
Each key carries one or more permissions (called scopes in the API).
| Scope | Shown in the app as | Allows |
|---|---|---|
chats:read | Read chats | List chats, read a chat and its messages, download deliverables, and stream live updates |
chats:write | Send messages | Create, rename, archive and delete chats, send messages, and stop a reply |
agents:read | List agents | List the workspace's agents and the agent templates |
workspaces:read | Read workspace | Read the workspace's name, status, and plan |
New keys start with Read chats and Send messages. There is no permission to create, change, or remove agents: adding an agent provisions a machine and changes your bill, so that stays in the app.
Two kinds of credential
| API key | Session token | |
|---|---|---|
| Looks like | bc_sk_… | bcs_… |
| Lasts | Until you revoke it | 10 minutes by default, 15 at most |
| Where it can live | Your server only | Anywhere, including a browser or mobile app |
| How you get one | Generate it in the app | Exchange an API key at POST /auth/sdk-token |
An API key is a long-lived secret. Keep it on your server: the API rejects a key sent from a browser or in a URL. For browser and mobile apps, your server exchanges the key for a short-lived session token and hands that out instead. See Authentication.
JavaScript SDK
Building in JavaScript or TypeScript? The BetterClaw JavaScript SDK wraps this API — chats, messages, live replies, and session-token refresh — with hooks for React and Vue.
npm install @better-claw/sdk
On a server, create a client with your API key using createServerClient from
@better-claw/sdk/server. In a browser, use BetterClawClient with SessionTokenAuth, and mint
tokens on your server with mintSessionToken. The
SDK's README has complete examples.
What you can call
| Method | Path | Scope |
|---|---|---|
GET | /workspaces | workspaces:read |
GET | /workspaces/{workspaceId} | workspaces:read |
GET | /workspaces/{workspaceId}/agents | agents:read |
GET | /workspaces/{workspaceId}/agents/{agentId} | agents:read |
GET | /workspaces/{workspaceId}/agents/templates | agents:read |
POST | /chats | chats:write |
GET | /chats?workspaceId={workspaceId} | chats:read |
GET | /chats/{chatId} | chats:read |
PATCH | /chats/{chatId} | chats:write |
DELETE | /chats/{chatId} | chats:write |
POST | /chats/{chatId}/messages | chats:write |
POST | /chats/{chatId}/messages/{messageId}/stop | chats:write |
GET | /chats/{chatId}/messages/{messageId}/deliverables/{index} | chats:read |
WS | /ws/chats?workspaceId={workspaceId} | chats:read |
POST | /auth/sdk-token | Any API key |
Everything else in the API, including managing keys themselves, needs a signed-in user and answers
an API key with 403.