Web API

Drive your agents from your own scripts.

The AgentX Web API is a JSON API for creating and steering your agents from your own scripts and tools. It sees every agent on every daemon you have claimed, the same as your console.

Let your coding agent write the calls

Recommended

Paste this prompt into Claude Code, Codex or any coding agent. It reads the API instructions, helps you set up a token without ever seeing it, and writes the calls with you. It asks you what you want done.

Help me use the AgentX Web API from this computer.
Read https://www.agentxhq.com/api.md and follow it.
Then ask me what I want my agents to do, and suggest a few examples.

API instructions for AI assistants (api.md) →OpenAPI description (openapi.json) →

What the API can do.

List your agents and chats across every daemon.
Send an agent a message and read its reply.
Create agents and chats.
Upload a file to an agent.
Claim a new daemon with its claim code.

Get an API token.

You create the token in your browser and keep it out of every chat. Only owners and admins of the account can create and use tokens.

Open Settings in the console and sign in. Check that the account you want to script is the one selected: a token works only for the account it was created in.
Find the API tokens card, type a name for the token under New API token, for example “my laptop scripts”, and click Create API token →.
The next page shows the token once. It starts with tok_. Copy it now; it is never shown again. The page also lists what the token is allowed to do.
Put it straight into an environment variable such as AGENTX_API_TOKEN in the terminal where your scripts run. Never paste it into a chat.

bash or zsh

read -rs AGENTX_API_TOKEN && export AGENTX_API_TOKEN

Paste the token and press Enter. Nothing is shown on screen.

PowerShell

$env:AGENTX_API_TOKEN = Read-Host -MaskInput "AgentX API token"

A token created in Settings does not expire and can do everything in the table below. To revoke it, click Revoke → next to it on the same card.

Base URL and sign-in.

Every call is plain HTTPS with JSON. Load the OpenAPI description first: it is the authority on field names and shapes, and it needs no token.

Base URL: https://www.agentxhq.com. Every path starts with /api/v1.
Auth header: Authorization: Bearer $AGENTX_API_TOKEN on every call except the two discovery routes.
Body: JSON with Content-Type: application/json, at most 1 MiB. File upload is multipart.
Discovery: /api/v1/openapi.json (OpenAPI 3.1), /api/v1 for a short index of every route, and /.well-known/api-catalog.

Try it

List your agents. If the answer has a non-empty unreachable list, one of your daemons could not be reached and the list is partial.

List agents

curl -s https://www.agentxhq.com/api/v1/agents \
  -H "Authorization: Bearer $AGENTX_API_TOKEN"

Endpoints

Eight routes in version 1. Each needs exactly one scope, and a token from Settings carries all of them.

Route	What it does	Scope
GET /api/v1/agents	List every agent across all your daemons.	agentx:agent.read
POST /api/v1/output	Read what an agent has been saying.	agentx:agent.read
POST /api/v1/agents	Create an agent on one of your daemons.	agentx:agent.create
POST /api/v1/agents/{agent}/upload	Upload a file into an agent's workspace.	agentx:agent.upload
GET /api/v1/bubbles	List chats, page by page with a cursor.	agentx:bubble.read
POST /api/v1/bubbles	Create a chat anchored to an agent.	agentx:bubble.create
POST /api/v1/messages	Send a message to an agent.	agentx:bubble.send
POST /api/v1/daemons/claim	Connect a daemon to your account with its claim code.	agentx:daemon.claim
GET /api/v1, /api/v1/openapi.json	Discovery. No token needed.	none

Field names, request bodies and responses are in the OpenAPI description. Only the routes listed there exist.

When a call is refused

Every refusal is JSON in one shape, {"error":{"code":…,"message":…}}, with the same code in the X-Error-Code header. Read the code and message; they say whether to fix the request, create a new token, or start or upgrade the daemon.

Need a person?

AgentX support is on Discord. Bring the status code and the error code from the response.