API
Everything the web app does goes through Agentome's HTTP API, so a script, a CI job or another system can do it too: file a task when something happens elsewhere, follow its run, decide an approval, set up agents and projects. This page shows how to sign in and make the first calls; the API reference lists every call.
Sign in with a token
Calls sign in with a personal API token, which acts as you: what you can do in the web app, the
token can do, or only read if you made it Read only. Make one under your name, API tokens
(see Make a token), and send it in the Authorization header.
Keep the address of your installation and the token in the environment, so neither ends up in a script:
export AGENTOME_URL=https://agentome.example.com
export AGENTOME_TOKEN=<the token>Check that it works by asking who you are:
curl -s "$AGENTOME_URL/api/me" -H "Authorization: Bearer $AGENTOME_TOKEN"A few calls that handle secrets answer only in the browser: making tokens, invitations and pairing codes, setting the keys of model and code-host connections, places on the server and notifications. A token that leaks cannot make more of itself or put a key of its own in place.
File a task and follow its run
Find the project and the agent, by name, in the lists:
curl -s "$AGENTOME_URL/api/projects" -H "Authorization: Bearer $AGENTOME_TOKEN"
curl -s "$AGENTOME_URL/api/agents" -H "Authorization: Bearer $AGENTOME_TOKEN"Then file the task. Without agentId it goes to the lead of the project's team; with run: false
it waits until someone starts it.
curl -s "$AGENTOME_URL/api/tasks" \
-H "Authorization: Bearer $AGENTOME_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"projectId": "<project id>",
"agentId": "<agent id>",
"title": "Add a dark theme to the settings page",
"body": "The settings page ignores the dark theme. Match the rest of the app."
}'The answer has the task and its queued run. Read the run until its status is no longer
queued or running:
curl -s "$AGENTOME_URL/api/runs/<run id>" -H "Authorization: Bearer $AGENTOME_TOKEN"Or follow it as it goes: /api/runs/<run id>/stream sends the run's events as server-sent events
until it ends, each as a run event, and its status as a status event.
curl -sN "$AGENTOME_URL/api/runs/<run id>/stream" -H "Authorization: Bearer $AGENTOME_TOKEN"When the run is done, the task is in Review: GET /api/tasks/<task id> has its runs, comments
and change requests, and POST /api/tasks/<task id>/comments asks for changes.
Decide approvals
GET /api/approvals lists the tool calls that wait for you, oldest first. Each one is decided with
POST /api/tool-calls/<id>/approve or /deny, and an agent's question is answered with /answer.
Only the agent's owner decides.
Errors
A refused call answers with its HTTP status and a body like this one, whose message is written for
a person:
{ "error": { "code": "not_found", "message": "Task not found" } }| Status | What it means |
|---|---|
| 400 | The body or a parameter is not what the call takes; details says which |
| 401 | No token, or one that has expired or was revoked |
| 403 | The token cannot do this: it only reads, the call needs the browser, or you may not |
| 404 | Nothing with that id, or nothing you may see |
| 409 | The state does not allow it now, such as a run that is already going |
| 502 | A code host, a model connection or a place did not answer |
The description
Each server describes its own API at /openapi.json, as OpenAPI 3, at the version it runs. Import
it into Postman or Insomnia, or generate a client from it. The
reference on this site is written from the description of
the latest release.
To manage agents, teams and projects from Claude Code or Codex in your own words rather than with calls, connect them to Agentome as an MCP server: see API tokens and managing Agentome from Claude Code or Codex.