Agent API

The Agent API is a way to control MultiAgent without the interface. Other programs and agents get access to factories, agents, tools and products through a set of commands locked behind a key. Whatever you do with buttons in the browser, an API caller can do automatically: for example, your assistant can create a factory, deploy a new agent and check that it works. The command set mirrors what the interface can do, but it is safer: secrets are accepted for writing only, there are no arbitrary commands, and long operations follow the proven “start it, then poll it” pattern. A program learns the available commands from the API itself — no separate documentation needed.

The key and how access is checked

Every request to /api/agent/ must carry the key in the X-API-Key header. MultiAgent never stores the key itself: the environment variable MULTIAGENT_HASH holds its “fingerprint” (a SHA-256 hash — a short string the key cannot be recovered from). On every request MultiAgent computes the fingerprint of the presented key and compares it with the stored one.

  • Variable not set — the whole API answers 503, “Agent API is disabled”: the API is off entirely;
  • Wrong or missing key — 401 Unauthorized (the attempt is logged with the client’s address);
  • Separate surfaces — the interface key does not open the API, and the API key does not open the browser pages.

Watch the end of the address: /api/agent/... is the program interface, opened by the key; /api/agents/... is the regular interface with sign-in by user account.

The catalog: GET /api/agent

The first request worth making is to GET /api/agent: it returns the full command catalog. It describes what MultiAgent controls, how the key check works (what the 503 and 401 errors mean), the basic concepts (factory, agent, product), how long operations run and how secrets are passed — plus every command: method, address, request fields and the response shape. The catalog is generated from the code, so it is always current — anyone who knows just the address and the key needs no separate documentation.

Long operations: start it, then poll it

Long operations — installing Docker, deploying agents and tools — all work the same way. The start command immediately returns an operation number, and your program asks for the status from time to time until it sees “done” or “failed”. It is like an order in a restaurant: you don’t have to wait by the stove — you get an order number and come back when the dish is ready. Re-issuing the start command is unnecessary — the operation is already running.

Behind every long operation stands a task in the shared queue: the work of one factory runs one operation at a time so the jobs don’t get in each other’s way. Until the queue reaches the task, the status request answers status: "queued" and there are no progress lines yet — that is a normal state, not an error. Wait for it to change to running.

POST /api/agent/factories               # created a factory
→ 202 { "operationId": "op_123", "message": "..." }

GET /api/agent/operations/op_123         # while the task waits in the queue
→ { "operationId": "op_123", "status": "queued", "lines": [] }

GET /api/agent/operations/op_123         # the task is running
→ { "operationId": "op_123", "kind": "...", "status": "running",
    "lines": [{ "text": "...", "isError": false }], ... }

GET /api/agent/operations/op_123         # final state
→ { "operationId": "op_123", "status": "done", "lines": [...], ... }

The status response contains lines — the operation’s progress lines in order, with the last line naming the outcome. Operation records live in memory and not forever: an unknown or expired operation number answers 404 with a hint to check the resource’s current state. Operations started from the browser are checked the same way.

Secrets — write-only

No API response ever contains a secret’s value — passwords, private keys, tokens. They are accepted on create and update, stored encrypted, and only indirect signs go out: whether a password is set (the hasPassword flag), whether there is a private key (hasPrivateKey), the names of extra variables, masked values.

There is deliberately no way to “peek” at a secret through the API: no revealing a service password, no exposing agent secrets, extra variable values, changing the manager’s password, or generating SSH keys. Handing out a generated private key via the API would give anyone holding the API key direct access to the machine — such actions are available only to a person in the interface.

Only predefined operations

Through the API you cannot run an arbitrary command on a factory — only MultiAgent’s predefined actions: install, clean, start, stop, deploy. Every operation’s input is limited to identifiers, names, ports and validated fields; no command accepts scripts or arbitrary configuration. Even the destructive actions (deleting a factory or a container with its data, cleaning up Docker) are predefined, well-bounded operations. This protection means: even a mistake or a failure in an automated client cannot do anything unplanned.

What you can do through the API

  • Core — the command catalog itself, the status of any operation by its number (including one started from the browser) and the instance’s build version, to notice updates;
  • Factories — the list with connection state, viewing one factory’s data and usage, checking installed services (docker, postgres, forgejo, rsync, nginx, the home page, the central login), an SSH connection test, a check with a list of findings and fix actions, create, update, delete — plus the long repair operations: install Docker, check, create folders and the agent user, clean up Docker, start a stopped Postgres, install postgres/forgejo/backups, import agents found on the machine. Separately: the shared database’s state (installed or only stopped), the list of databases in its container and a full reinstall in one call; a manual sync of the Forgejo sign-in with the central login; choosing a repository across all factories at once; the readiness of local servers on the Windows Subsystem for Linux (WSL); a preview of an upcoming factory handover. The factory’s shared environment variables are returned by name only — values go one way;
  • Nginx — the factory’s public access: Nginx status and install, certificates (custom, self-signed, a Let’s Encrypt request — a long operation with progress), enabling the HTTPS port, renewing a certificate and downloading the public chain, custom routes (create, update, delete);
  • Authorization — the central login’s lifecycle: check, install, apply settings, remove while keeping data and secrets;
  • Home page — reading the state and installing and updating the static board at the factory’s root;
  • Models — MultiAgent’s model catalog (list, create, update, delete), pushing a model onto chosen agents — the same-named agent record is replaced, with the outcome per agent; changing a private variable recreates the agent’s container — and importing from an agent (same-named catalog records are replaced, keeping the schedule and icon); private variables are masked in responses — only the “value is set” sign goes out;
  • Skills — MultiAgent’s skill catalog (list, read files, create, update, delete — the copies on agents remain), pushing a skill onto chosen agents as an exact replacement of the same-named folder, and importing from an agent with replacement on name match;
  • Accounts — list, create, update and delete accounts at model providers, reading the quota (from the temporary store or with a fresh provider check), the model-usage history by day, the Codex device-code sign-in and sign-out. Keys and tokens are write-only;
  • Analytics — all agent reporting is read-only, with the same conditions as in the browser (one agent, labels, the chosen fleet, dates), plus starting the ClickHouse history backfill and reading its status;
  • Account statistics — the same reporting, but over provider accounts: balance and quota over time, cuts by provider and by account, distributions, averages by hour and day of week, and the latest snapshots;
  • Licenses — MultiAgent’s own license status and setting a new key; the key is write-only;
  • Agent licenses — the agent license pool: list, create, update, extending for a term, delete and the assignments — which agents use it; issuing a new key right on the machine when the signing key sits there. The key is always masked, and a license in use cannot be deleted — a conflict with the reference count;
  • Agents — the list with type (regular agent or product), slug, port, public address and container state; viewing state (status, logs, statistics, configuration, API check); creating — the port is picked automatically, for products — from the product catalog with variables; the lifecycle: deploy, start, stop, restart, update, recreate, delete. Here too — the Git plumbing and agent databases: the factory’s Forgejo repository list (honoring the organization from the “Company” field), creating a repository and linking it to an agent (or linking an existing one), checking external database credentials before creating an agent, testing an agent database’s own credentials, and reading references — what currently points at the agent (handy before a deletion). There is no separate “pull image” command — recreating pulls a fresh image itself;
  • Chats — transparent access to the agent’s own program interface: read the chat list, send a message, get the reply — exactly the way the browser does it;
  • Tools — tool templates (the catalog and the full description with variables) and installing them on a factory with variable validation; an installed tool’s state, logs and statistics can be read, its port publicness and central-login protection toggled, and its image updated and container recreated;
  • Products — the product catalog for reading, with the descriptions of every product’s variables;
  • Move — accepting a full set of one factory’s records from another MultiAgent instance: this is how the receiving side of a handover takes in the connection, the factory, the agents and products with their secrets, the tools, the routes and the certificates;
  • Session — a one-time code to sign into the interface without a password (for when a human sign-in is genuinely needed);
  • Decisions — an agent can hand the operator a question, a notification or a review request (with a cost and risk estimate) and read its own active items. A cancellable action costing less than 500 dollars approves itself and never reaches the queue (a trace stays in the journal); an expensive one (from 5000 dollars) or an irreversible one becomes blocking, and the rest queues up normally. A repeat with the same key increments the counter of the item already standing instead of creating a duplicate.

Example calls

# The catalog — the surface's self-describing documentation
curl -H "X-API-Key: my-key" https://multiagent.example.com/api/agent

# The factory list with connection state
curl -H "X-API-Key: my-key" https://multiagent.example.com/api/agent/factories

# Create a factory: the connection is either the number of an existing
# server record, or the full connection fields (server, username,
# password/privateKey, sshPort)
curl -X POST -H "X-API-Key: my-key" -H "Content-Type: application/json" \
  -d '{"name":"Prod","slug":"prod","serverId":3}' \
  https://multiagent.example.com/api/agent/factories
# or: -d '{"name":"Prod","slug":"prod","server":"10.0.0.5","sshPort":22,"username":"root","password":"…"}'

# Create an agent and deploy it (202 + polling operations/{id} for status)
curl -X POST -H "X-API-Key: my-key" -H "Content-Type: application/json" \
  -d '{"name":"bot","factoryId":3,"slug":"bot"}' \
  https://multiagent.example.com/api/agent/agents
curl -X POST https://multiagent.example.com/api/agent/agents/42/provision

# Factory checks: 202, the operation carries structured results with fix actions
curl -X POST -H "X-API-Key: my-key" https://multiagent.example.com/api/agent/factories/3/check
# polling operations/{id} returns checks[]: code, status, details and a fix action

# Model: push to chosen agents (replaces the same-named record)
curl -X POST -H "X-API-Key: my-key" -H "Content-Type: application/json" \
  -d '{"agentIds":[3,4]}' \
  https://multiagent.example.com/api/agent/models/12/push

The error format is uniform — the response body is always { error, message }. Bad input — 400 InvalidRequest; an unknown resource — 404 NotFound; conflicts (for example, deleting a factory that agents still reference) — 409 Conflict with the number of affected agents; license limits on creating — 403 with an expired-license flag; an unreachable machine on a check that needs it — 502 RemoteError with the reason. API messages are in English.

The Agent API is not the only machine entrance. When all you need is the analytics numbers, there is the GraphQL query language at /graphql: the same report as the “Tokens”, “Cost”, “Speed” and “Chats” screens, read-only and with its own password — details on the Analytics and exports page.

← Back to documentation