API reference
Agentome 0.3.0. Every call of the HTTP API by section: what it does, what it takes and what it answers.
Everything the Agentome web app does goes through this API, so a script can do it too: file tasks, follow runs, decide approvals, set up agents and projects.
Address. Your installation's address with the paths below, such as
https://agentome.example.com/api/agents. Each server describes its own API at /openapi.json.
Signing in. Make a token in Agentome under your name, API tokens, and send it in the
Authorization header: Authorization: Bearer <token>. The token acts as you and can do what you
can, or only read if you made it that way. A few calls that handle secrets (tokens, keys, places,
notifications) answer only in the browser.
Errors. A refused call answers with its HTTP status and
{ "error": { "code": "not_found", "message": "…" } }; the message is written for a person.
The same as OpenAPI 3: openapi.json, for Postman, Insomnia or a client generator. Each server also serves its own at /openapi.json.
Agents
Agents with their instructions, model, tools, skills, MCP servers, memory and recurring tasks.
GET /api/templates
The platform's role templates.
Answer 200
templatesarray of objectFields of
templatesiduuidnamestringversionintegerdescriptionstringroleTitlestringmodelPrefstring or null
GET /api/agents
Agents the person has a grant on; every agent with all=true, for admins.
Query
archived"true" or "false"default "false"
all"true" or "false"default "false"
Answer 200
agentsarray of objectFields of
agentsiduuidnamestringroleTitlestringstatus"active" or "archived"ownerobjectFields of
owneriduuidnamestring
lastRunobject or nullFields of
lastRuniduuidtaskIduuid or nullstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-timetaskobject or nullFields of
tasktitlestringprojectstring or null
createdAtdate-timemodelPrefstring or nullweekobjectFields of
weekrunsintegerusdstring or nullendedintegerdoneintegermedianSecondsinteger or nulldailyarray of integerup to 7 items
monthobjectFields of
monthacceptedintegerhandedintegermedianUsdstring or null
POST /api/agents
Creates an agent, blank or from a role template, owned by the person.
Body
namestring required1 to 100 characters
roleTitlestringup to 200 characters
templateIduuid
Answer 201
iduuidnamestringroleTitlestringstatus"active" or "archived"ownerobjectFields of
owneriduuidnamestring
lastRunobject or nullFields of
lastRuniduuidtaskIduuid or nullstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-timetaskobject or nullFields of
tasktitlestringprojectstring or null
createdAtdate-timeinstructionsstringengine"claude-code" or "codex"modelPrefstring or nullrunsOn"laptop" or "server"modelConnectionobject or nullFields of
modelConnectioniduuidnamestring
serverShellbooleanbudgetobject or nullFields of
budgetmaxMinutesinteger optionalmaxTurnsinteger optionalmaxTokensinteger optionalusdPerMonthnumber optional0 to 1,000,000
runDefaultsobjectFields of
runDefaultsmaxMinutesintegermaxTurnsintegermaxTokensinteger
copiedFromAgentIduuid or nulltemplateobject or nullFields of
templateiduuidnamestringversioninteger
seatobject or nullFields of
seatiduuidnamestringbusybooleanlastSeenAtdate-time or null
peoplearray of objectFields of
peopleiduuidnamestringlevel"owner"validFromdate-time or nullvalidUntildate-time or null
projectsarray of objectFields of
projectsiduuidnamestringhostsarray of "github" or "gitlab" or "jira"repositoriesarray of string
toolsarray of objectFields of
toolsconnectorstringnamestringtitlestringpolicy"allow" or "ask" or "deny"
skillsarray of objectFields of
skillsiduuidnamestringversionstringprivateTostring optional
mcpServersarray of objectFields of
mcpServersiduuidnamestringprivateTostring optional
memoryDocumentsintegerspendobjectFields of
spendusdThisMonthnumberlimitnumber or nullreachedbooleanresumedboolean
GET /api/agents/{id}
Everything the editor and the agent sheet show.
Path
iduuid required
Answer 200
iduuidnamestringroleTitlestringstatus"active" or "archived"ownerobjectFields of
owneriduuidnamestring
lastRunobject or nullFields of
lastRuniduuidtaskIduuid or nullstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-timetaskobject or nullFields of
tasktitlestringprojectstring or null
createdAtdate-timeinstructionsstringengine"claude-code" or "codex"modelPrefstring or nullrunsOn"laptop" or "server"modelConnectionobject or nullFields of
modelConnectioniduuidnamestring
serverShellbooleanbudgetobject or nullFields of
budgetmaxMinutesinteger optionalmaxTurnsinteger optionalmaxTokensinteger optionalusdPerMonthnumber optional0 to 1,000,000
runDefaultsobjectFields of
runDefaultsmaxMinutesintegermaxTurnsintegermaxTokensinteger
copiedFromAgentIduuid or nulltemplateobject or nullFields of
templateiduuidnamestringversioninteger
seatobject or nullFields of
seatiduuidnamestringbusybooleanlastSeenAtdate-time or null
peoplearray of objectFields of
peopleiduuidnamestringlevel"owner"validFromdate-time or nullvalidUntildate-time or null
projectsarray of objectFields of
projectsiduuidnamestringhostsarray of "github" or "gitlab" or "jira"repositoriesarray of string
toolsarray of objectFields of
toolsconnectorstringnamestringtitlestringpolicy"allow" or "ask" or "deny"
skillsarray of objectFields of
skillsiduuidnamestringversionstringprivateTostring optional
mcpServersarray of objectFields of
mcpServersiduuidnamestringprivateTostring optional
memoryDocumentsintegerspendobjectFields of
spendusdThisMonthnumberlimitnumber or nullreachedbooleanresumedboolean
PATCH /api/agents/{id}
Changes the identity, instructions, model or budget.
Path
iduuid required
Body
namestring1 to 100 characters
roleTitlestringup to 200 characters
instructionsstringup to 100,000 characters
modelPrefstring or nullup to 100 characters
engine"claude-code" or "codex"budgetobject or nullFields of
budgetmaxMinutesintegermaxTurnsintegermaxTokensintegerusdPerMonthnumber0 to 1,000,000
runsOn"laptop" or "server"modelConnectionIduuid or nullserverShellboolean
Answer 200
iduuidnamestringroleTitlestringstatus"active" or "archived"ownerobjectFields of
owneriduuidnamestring
lastRunobject or nullFields of
lastRuniduuidtaskIduuid or nullstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-timetaskobject or nullFields of
tasktitlestringprojectstring or null
createdAtdate-timeinstructionsstringengine"claude-code" or "codex"modelPrefstring or nullrunsOn"laptop" or "server"modelConnectionobject or nullFields of
modelConnectioniduuidnamestring
serverShellbooleanbudgetobject or nullFields of
budgetmaxMinutesinteger optionalmaxTurnsinteger optionalmaxTokensinteger optionalusdPerMonthnumber optional0 to 1,000,000
runDefaultsobjectFields of
runDefaultsmaxMinutesintegermaxTurnsintegermaxTokensinteger
copiedFromAgentIduuid or nulltemplateobject or nullFields of
templateiduuidnamestringversioninteger
seatobject or nullFields of
seatiduuidnamestringbusybooleanlastSeenAtdate-time or null
peoplearray of objectFields of
peopleiduuidnamestringlevel"owner"validFromdate-time or nullvalidUntildate-time or null
projectsarray of objectFields of
projectsiduuidnamestringhostsarray of "github" or "gitlab" or "jira"repositoriesarray of string
toolsarray of objectFields of
toolsconnectorstringnamestringtitlestringpolicy"allow" or "ask" or "deny"
skillsarray of objectFields of
skillsiduuidnamestringversionstringprivateTostring optional
mcpServersarray of objectFields of
mcpServersiduuidnamestringprivateTostring optional
memoryDocumentsintegerspendobjectFields of
spendusdThisMonthnumberlimitnumber or nullreachedbooleanresumedboolean
GET /api/agents/{id}/quality
The agent's last 30 days: tasks accepted, tasks that came back, merged change requests, cost and time per task, failed runs.
Path
iduuid required
Answer 200
tasksintegerhandedintegeracceptedintegerfirstTimeintegerchangeRequestsobjectFields of
changeRequestsmergedintegerclosedintegeropeninteger
returnsobjectFields of
returnstotalintegertasksintegerpersonintegerciintegerreviewinteger
usdobjectFields of
usdmedianstring or nulltotalstring or null
secondsobjectFields of
secondsworkinteger or nulltoReviewinteger or null
runsobjectFields of
runsendedintegerfailedintegerlimitedinteger
sincedate-timemostReturnedarray of objectFields of
mostReturnediduuidtitlestringreturnsintegerusdstring or null
POST /api/agents/{id}/budget/resume
Lets the agent go on past its monthly limit until the month ends.
Path
iduuid required
Answer 200
iduuidnamestringroleTitlestringstatus"active" or "archived"ownerobjectFields of
owneriduuidnamestring
lastRunobject or nullFields of
lastRuniduuidtaskIduuid or nullstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-timetaskobject or nullFields of
tasktitlestringprojectstring or null
createdAtdate-timeinstructionsstringengine"claude-code" or "codex"modelPrefstring or nullrunsOn"laptop" or "server"modelConnectionobject or nullFields of
modelConnectioniduuidnamestring
serverShellbooleanbudgetobject or nullFields of
budgetmaxMinutesinteger optionalmaxTurnsinteger optionalmaxTokensinteger optionalusdPerMonthnumber optional0 to 1,000,000
runDefaultsobjectFields of
runDefaultsmaxMinutesintegermaxTurnsintegermaxTokensinteger
copiedFromAgentIduuid or nulltemplateobject or nullFields of
templateiduuidnamestringversioninteger
seatobject or nullFields of
seatiduuidnamestringbusybooleanlastSeenAtdate-time or null
peoplearray of objectFields of
peopleiduuidnamestringlevel"owner"validFromdate-time or nullvalidUntildate-time or null
projectsarray of objectFields of
projectsiduuidnamestringhostsarray of "github" or "gitlab" or "jira"repositoriesarray of string
toolsarray of objectFields of
toolsconnectorstringnamestringtitlestringpolicy"allow" or "ask" or "deny"
skillsarray of objectFields of
skillsiduuidnamestringversionstringprivateTostring optional
mcpServersarray of objectFields of
mcpServersiduuidnamestringprivateTostring optional
memoryDocumentsintegerspendobjectFields of
spendusdThisMonthnumberlimitnumber or nullreachedbooleanresumedboolean
POST /api/agents/{id}/duplicate
Copies the configuration into a new agent of the person; grants stay behind.
Path
iduuid required
Answer 201
iduuidnamestringroleTitlestringstatus"active" or "archived"ownerobjectFields of
owneriduuidnamestring
lastRunobject or nullFields of
lastRuniduuidtaskIduuid or nullstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-timetaskobject or nullFields of
tasktitlestringprojectstring or null
createdAtdate-timeinstructionsstringengine"claude-code" or "codex"modelPrefstring or nullrunsOn"laptop" or "server"modelConnectionobject or nullFields of
modelConnectioniduuidnamestring
serverShellbooleanbudgetobject or nullFields of
budgetmaxMinutesinteger optionalmaxTurnsinteger optionalmaxTokensinteger optionalusdPerMonthnumber optional0 to 1,000,000
runDefaultsobjectFields of
runDefaultsmaxMinutesintegermaxTurnsintegermaxTokensinteger
copiedFromAgentIduuid or nulltemplateobject or nullFields of
templateiduuidnamestringversioninteger
seatobject or nullFields of
seatiduuidnamestringbusybooleanlastSeenAtdate-time or null
peoplearray of objectFields of
peopleiduuidnamestringlevel"owner"validFromdate-time or nullvalidUntildate-time or null
projectsarray of objectFields of
projectsiduuidnamestringhostsarray of "github" or "gitlab" or "jira"repositoriesarray of string
toolsarray of objectFields of
toolsconnectorstringnamestringtitlestringpolicy"allow" or "ask" or "deny"
skillsarray of objectFields of
skillsiduuidnamestringversionstringprivateTostring optional
mcpServersarray of objectFields of
mcpServersiduuidnamestringprivateTostring optional
memoryDocumentsintegerspendobjectFields of
spendusdThisMonthnumberlimitnumber or nullreachedbooleanresumedboolean
POST /api/agents/{id}/transfer
Transfers the agent, and a lead's whole team with it, to another person: for good, or until a day it comes back; its owner or an admin.
Path
iduuid required
Body
touuid requireduntildate-time
Answer 200
transferredarray of objectFields of
transferrediduuidnamestring
toobjectFields of
toiduuidnamestring
untildate-time or null
GET /api/agents/{id}/export
The configuration as a JSON file, without ids, grants or secrets.
Path
iduuid required
Answer 200
format"agentome/agent@2"agentobjectFields of
agentnamestring1 to 100 characters
roleTitlestringup to 200 characters
instructionsstringup to 100,000 characters
engine"claude-code" or "codex"modelPrefstring or nullup to 100 characters
budgetobject or nullFields of
budgetmaxMinutesinteger optionalmaxTurnsinteger optionalmaxTokensinteger optionalusdPerMonthnumber optional0 to 1,000,000
templateobject or nullFields of
templatenamestringversioninteger
skillsarray of objectup to 50 items
Fields of
skillscontentstring1 to 100,000 characters
toolsarray of objectup to 500 items
Fields of
toolsnamestringup to 200 characters
policy"allow" or "ask" or "deny"
mcpServersarray of objectup to 50 items
Fields of
mcpServersnamestringup to 100 characters
sourceobject optionalFields of
sourcenamestringup to 200 characters
urluriup to 500 characters
licensestringup to 100 characters
POST /api/agents/import
A new agent of the person from an agent file; its skills join their library.
Body
any
Answer 201
agentobjectFields of
agentiduuidnamestring
skillsarray of objectFields of
skillsnamestringversionintegeraddedboolean
missingServersarray of string
POST /api/agents/{id}/archive
Archives the agent: its queued runs are cancelled and it takes no more.
Path
iduuid required
Answer 200
iduuidnamestringroleTitlestringstatus"active" or "archived"ownerobjectFields of
owneriduuidnamestring
lastRunobject or nullFields of
lastRuniduuidtaskIduuid or nullstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-timetaskobject or nullFields of
tasktitlestringprojectstring or null
createdAtdate-timeinstructionsstringengine"claude-code" or "codex"modelPrefstring or nullrunsOn"laptop" or "server"modelConnectionobject or nullFields of
modelConnectioniduuidnamestring
serverShellbooleanbudgetobject or nullFields of
budgetmaxMinutesinteger optionalmaxTurnsinteger optionalmaxTokensinteger optionalusdPerMonthnumber optional0 to 1,000,000
runDefaultsobjectFields of
runDefaultsmaxMinutesintegermaxTurnsintegermaxTokensinteger
copiedFromAgentIduuid or nulltemplateobject or nullFields of
templateiduuidnamestringversioninteger
seatobject or nullFields of
seatiduuidnamestringbusybooleanlastSeenAtdate-time or null
peoplearray of objectFields of
peopleiduuidnamestringlevel"owner"validFromdate-time or nullvalidUntildate-time or null
projectsarray of objectFields of
projectsiduuidnamestringhostsarray of "github" or "gitlab" or "jira"repositoriesarray of string
toolsarray of objectFields of
toolsconnectorstringnamestringtitlestringpolicy"allow" or "ask" or "deny"
skillsarray of objectFields of
skillsiduuidnamestringversionstringprivateTostring optional
mcpServersarray of objectFields of
mcpServersiduuidnamestringprivateTostring optional
memoryDocumentsintegerspendobjectFields of
spendusdThisMonthnumberlimitnumber or nullreachedbooleanresumedboolean
POST /api/agents/{id}/unarchive
Brings an archived agent back.
Path
iduuid required
Answer 200
iduuidnamestringroleTitlestringstatus"active" or "archived"ownerobjectFields of
owneriduuidnamestring
lastRunobject or nullFields of
lastRuniduuidtaskIduuid or nullstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-timetaskobject or nullFields of
tasktitlestringprojectstring or null
createdAtdate-timeinstructionsstringengine"claude-code" or "codex"modelPrefstring or nullrunsOn"laptop" or "server"modelConnectionobject or nullFields of
modelConnectioniduuidnamestring
serverShellbooleanbudgetobject or nullFields of
budgetmaxMinutesinteger optionalmaxTurnsinteger optionalmaxTokensinteger optionalusdPerMonthnumber optional0 to 1,000,000
runDefaultsobjectFields of
runDefaultsmaxMinutesintegermaxTurnsintegermaxTokensinteger
copiedFromAgentIduuid or nulltemplateobject or nullFields of
templateiduuidnamestringversioninteger
seatobject or nullFields of
seatiduuidnamestringbusybooleanlastSeenAtdate-time or null
peoplearray of objectFields of
peopleiduuidnamestringlevel"owner"validFromdate-time or nullvalidUntildate-time or null
projectsarray of objectFields of
projectsiduuidnamestringhostsarray of "github" or "gitlab" or "jira"repositoriesarray of string
toolsarray of objectFields of
toolsconnectorstringnamestringtitlestringpolicy"allow" or "ask" or "deny"
skillsarray of objectFields of
skillsiduuidnamestringversionstringprivateTostring optional
mcpServersarray of objectFields of
mcpServersiduuidnamestringprivateTostring optional
memoryDocumentsintegerspendobjectFields of
spendusdThisMonthnumberlimitnumber or nullreachedbooleanresumedboolean
PUT /api/agents/{id}/tools/{name}
Sets the policy of one gateway tool: allow, ask the owner, or deny.
Path
iduuid requirednamestring requiredup to 200 characters
Body
policy"allow" or "ask" or "deny" required
Answer 200
iduuidnamestringroleTitlestringstatus"active" or "archived"ownerobjectFields of
owneriduuidnamestring
lastRunobject or nullFields of
lastRuniduuidtaskIduuid or nullstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-timetaskobject or nullFields of
tasktitlestringprojectstring or null
createdAtdate-timeinstructionsstringengine"claude-code" or "codex"modelPrefstring or nullrunsOn"laptop" or "server"modelConnectionobject or nullFields of
modelConnectioniduuidnamestring
serverShellbooleanbudgetobject or nullFields of
budgetmaxMinutesinteger optionalmaxTurnsinteger optionalmaxTokensinteger optionalusdPerMonthnumber optional0 to 1,000,000
runDefaultsobjectFields of
runDefaultsmaxMinutesintegermaxTurnsintegermaxTokensinteger
copiedFromAgentIduuid or nulltemplateobject or nullFields of
templateiduuidnamestringversioninteger
seatobject or nullFields of
seatiduuidnamestringbusybooleanlastSeenAtdate-time or null
peoplearray of objectFields of
peopleiduuidnamestringlevel"owner"validFromdate-time or nullvalidUntildate-time or null
projectsarray of objectFields of
projectsiduuidnamestringhostsarray of "github" or "gitlab" or "jira"repositoriesarray of string
toolsarray of objectFields of
toolsconnectorstringnamestringtitlestringpolicy"allow" or "ask" or "deny"
skillsarray of objectFields of
skillsiduuidnamestringversionstringprivateTostring optional
mcpServersarray of objectFields of
mcpServersiduuidnamestringprivateTostring optional
memoryDocumentsintegerspendobjectFields of
spendusdThisMonthnumberlimitnumber or nullreachedbooleanresumedboolean
PUT /api/agents/{id}/tools
Auto or manual: every gateway tool of the agent allowed, or asking its owner; the ones denied stay denied.
Path
iduuid required
Body
policy"allow" or "ask" required
Answer 200
iduuidnamestringroleTitlestringstatus"active" or "archived"ownerobjectFields of
owneriduuidnamestring
lastRunobject or nullFields of
lastRuniduuidtaskIduuid or nullstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-timetaskobject or nullFields of
tasktitlestringprojectstring or null
createdAtdate-timeinstructionsstringengine"claude-code" or "codex"modelPrefstring or nullrunsOn"laptop" or "server"modelConnectionobject or nullFields of
modelConnectioniduuidnamestring
serverShellbooleanbudgetobject or nullFields of
budgetmaxMinutesinteger optionalmaxTurnsinteger optionalmaxTokensinteger optionalusdPerMonthnumber optional0 to 1,000,000
runDefaultsobjectFields of
runDefaultsmaxMinutesintegermaxTurnsintegermaxTokensinteger
copiedFromAgentIduuid or nulltemplateobject or nullFields of
templateiduuidnamestringversioninteger
seatobject or nullFields of
seatiduuidnamestringbusybooleanlastSeenAtdate-time or null
peoplearray of objectFields of
peopleiduuidnamestringlevel"owner"validFromdate-time or nullvalidUntildate-time or null
projectsarray of objectFields of
projectsiduuidnamestringhostsarray of "github" or "gitlab" or "jira"repositoriesarray of string
toolsarray of objectFields of
toolsconnectorstringnamestringtitlestringpolicy"allow" or "ask" or "deny"
skillsarray of objectFields of
skillsiduuidnamestringversionstringprivateTostring optional
mcpServersarray of objectFields of
mcpServersiduuidnamestringprivateTostring optional
memoryDocumentsintegerspendobjectFields of
spendusdThisMonthnumberlimitnumber or nullreachedbooleanresumedboolean
GET /api/agents/{id}/workspace-preview
The CLAUDE.md and settings a run of the agent gets, as it is saved.
Path
iduuid required
Answer 200
claudeMdstringprojectMdstring optionalsettingsobjectFields of
settingspermissionMode"acceptEdits"allowedToolsarray of stringsandboxobjectFields of
sandboxenabledbooleanfailIfUnavailablebooleanautoAllowBashIfSandboxedbooleanallowUnsandboxedCommandsfalsenetworkobjectFields of
networkallowedDomainsarray of stringstrictAllowlisttrueallowLocalBindingtrue optional
GET /api/agents/{id}/memory
The agent's memory documents as they are now.
Path
iduuid required
Answer 200
documentsarray of objectFields of
documentspathstringversionintegercontentstringupdatedAtdate-timeupdatedByobject or object
PUT /api/agents/{id}/memory
Writes a new version of a memory document.
Path
iduuid required
Body
pathstring requiredcontentstring required1 to 100,000 characters
baseVersioninteger
Answer 200
pathstringversionintegercontentstringupdatedAtdate-timeupdatedByobject or object
DELETE /api/agents/{id}/memory
Deletes a memory document; its history stays.
Path
iduuid required
Query
pathstring requiredbaseVersioninteger
Answer
200.
GET /api/agents/{id}/memory/versions
Every version of one memory document, newest first.
Path
iduuid required
Query
pathstring required
Answer 200
pathstringversionsarray of objectFields of
versionspathstringversionintegercontentstringupdatedAtdate-timeupdatedByobject or object
POST /api/agents/{id}/memory/revert
Brings back an earlier version of a memory document, as a new version.
Path
iduuid required
Body
pathstring requiredversioninteger required
Answer 200
pathstringversionintegercontentstringupdatedAtdate-timeupdatedByobject or object
PUT /api/agents/{id}/skills
Sets the agent's skills, each at the version given.
Path
iduuid required
Body
skillsarray of uuid requiredup to 50 items
Answer 200
skillsarray of objectFields of
skillsiduuidnamestringdescriptionstringversionintegerownerobject or nullFields of
owneriduuidnamestring
visibility"org" or "private"createdAtdate-time
PUT /api/agents/{id}/mcp
Sets the agent's MCP servers; their tools ask the owner until a policy says otherwise.
Path
iduuid required
Body
serversarray of uuid requiredup to 20 items
Answer 200
serversarray of objectFields of
serversiduuidnamestringdescriptionstringurlstringhasAuthorizationbooleanauth"header" or "oauth"signedInbooleantoolsarray of objectFields of
toolsnamestringtitlestringdescriptionstring
checkedAtdate-timeownerobject or nullFields of
owneriduuidnamestring
visibility"org" or "private"
GET /api/agents/{id}/schedules
The agent's recurring tasks.
Path
iduuid required
Answer 200
schedulesarray of objectFields of
schedulesiduuidtitlestringbodystringprojectIduuid or nullrepositorystring or nulldaysarray of integertimestringtimeZonestringenabledbooleanwhenstringlastRunAtdate-time or null
POST /api/agents/{id}/schedules
Adds a recurring task: on these days (0 is Sunday) at this HH:MM in this time zone, a task is made and run.
Path
iduuid required
Body
titlestring required1 to 200 characters
bodystringup to 100,000 characters
projectIduuid requiredrepositorystring or nullup to 2,000 characters; default null
daysarray of integer requiredup to 7 items
timestring requiredtimeZonestring requiredenabledbooleandefault true
Answer 201
iduuidtitlestringbodystringprojectIduuid or nullrepositorystring or nulldaysarray of integertimestringtimeZonestringenabledbooleanwhenstringlastRunAtdate-time or null
PATCH /api/agents/{id}/schedules/{scheduleId}
Changes a recurring task, or turns it off and on.
Path
iduuid requiredscheduleIduuid required
Body
titlestring1 to 200 characters
bodystringup to 100,000 characters
projectIduuidrepositorystring or nullup to 2,000 characters; default null
daysarray of integerup to 7 items
timestringtimeZonestringenabledbooleandefault true
Answer 200
iduuidtitlestringbodystringprojectIduuid or nullrepositorystring or nulldaysarray of integertimestringtimeZonestringenabledbooleanwhenstringlastRunAtdate-time or null
DELETE /api/agents/{id}/schedules/{scheduleId}
Removes a recurring task.
Path
iduuid requiredscheduleIduuid required
Answer
200.
Tasks
Tasks in projects, their comments and their runs.
GET /api/tasks
Tasks of the agents the person has a grant on; every task with all=true, for admins.
Query
agentuuidprojectuuidstatus"open" or "review" or "done"limitinteger1 to 100; default 50
beforestringallstring
Answer 200
tasksarray of objectFields of
tasksiduuidtitlestringagentobjectFields of
agentiduuidnamestring
status"open" or "review" or "done"source"manual" or "jira" or "cron" or "webhook" or "chat" or "agent"repositorystring or nullrepositoryFromProjectbooleancreatedByobjectFields of
createdByiduuidnamestring
createdAtdate-timelatestRunobject or nullFields of
latestRuniduuidstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-time
projectobject or nullFields of
projectiduuidnamestring
changeRequestobject or nullFields of
changeRequeststate"open" or "draft" or "merged" or "closed" or nulldefault null
pipeline"none" or "running" or "success" or "failed" or nulldefault null
urlstring
nextBeforestring or null
POST /api/tasks
Creates a manual task in a project and, unless run is false, queues its run. Without agentId it goes to the project's team lead in the project's main repository, and runs at once when the project's intake is auto.
Body
projectIduuid requiredagentIduuidtitlestring required1 to 200 characters
bodystringup to 100,000 characters
repositorystring or nullup to 2,000 characters
runboolean
Answer 201
taskobjectFields of
taskiduuidtitlestringagentobjectFields of
agentiduuidnamestringstatus"active" or "archived"
status"open" or "review" or "done"source"manual" or "jira" or "cron" or "webhook" or "chat" or "agent"repositorystring or nullrepositoryFromProjectbooleancreatedByobjectFields of
createdByiduuidnamestring
createdAtdate-timelatestRunobject or nullFields of
latestRuniduuidstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-time
projectobject or nullFields of
projectiduuidnamestring
changeRequestobject or nullFields of
changeRequeststate"open" or "draft" or "merged" or "closed" or nulldefault null
pipeline"none" or "running" or "success" or "failed" or nulldefault null
urlstring
bodystringexternalErrorstring or nullconnectionobject or nullFields of
connectioniduuidkind"github" or "gitlab" or "jira"projectobjectFields of
projectiduuidnamestring
parentobject or nullFields of
parentiduuidtitlestringagentstring
subtasksarray of objectFields of
subtasksiduuidtitlestringagentstringstatus"open" or "review" or "done"runStatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled" or null
runsarray of objectFields of
runsiduuidstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"startedAtdate-time or nullendedAtdate-time or nullerrorCodestring or nullsummarystring or nullseatobject or nullFields of
seatnamestring
createdAtdate-timeusdstring or null
changeRequestsarray of objectFields of
changeRequestsstate"open" or "draft" or "merged" or "closed" or nulldefault null
pipeline"none" or "running" or "success" or "failed" or nulldefault null
review"approved" or "changes_requested" or "commented" or nulldefault null
urlstringrunIdstringcreatedAtdate-time
commentsarray of objectFields of
commentsiduuidbodystringrunIduuid or nullcreatedAtdate-timeauthorobjectFields of
authorkind"person" or "agent"iduuidnamestring
questionsarray of objectFields of
questionsiduuidrunIduuidquestionstringanswerstring or nullstate"waiting" or "answered" or "skipped" or "unanswered"askedAtdate-timeansweredAtdate-time or nullansweredBystring or null
runobject or nullFields of
runiduuidstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
GET /api/tasks/folders
Folders on a computer the person's own tasks worked in, the most recent first: what the task form offers before a path is typed.
Answer 200
foldersarray of string
GET /api/tasks/{id}
A task with its description and its runs, newest first.
Path
iduuid required
Answer 200
iduuidtitlestringagentobjectFields of
agentiduuidnamestringstatus"active" or "archived"
status"open" or "review" or "done"source"manual" or "jira" or "cron" or "webhook" or "chat" or "agent"repositorystring or nullrepositoryFromProjectbooleancreatedByobjectFields of
createdByiduuidnamestring
createdAtdate-timelatestRunobject or nullFields of
latestRuniduuidstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-time
projectobject or nullFields of
projectiduuidnamestring
changeRequestobject or nullFields of
changeRequeststate"open" or "draft" or "merged" or "closed" or nulldefault null
pipeline"none" or "running" or "success" or "failed" or nulldefault null
urlstring
bodystringexternalErrorstring or nullconnectionobject or nullFields of
connectioniduuidkind"github" or "gitlab" or "jira"projectobjectFields of
projectiduuidnamestring
parentobject or nullFields of
parentiduuidtitlestringagentstring
subtasksarray of objectFields of
subtasksiduuidtitlestringagentstringstatus"open" or "review" or "done"runStatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled" or null
runsarray of objectFields of
runsiduuidstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"startedAtdate-time or nullendedAtdate-time or nullerrorCodestring or nullsummarystring or nullseatobject or nullFields of
seatnamestring
createdAtdate-timeusdstring or null
changeRequestsarray of objectFields of
changeRequestsstate"open" or "draft" or "merged" or "closed" or nulldefault null
pipeline"none" or "running" or "success" or "failed" or nulldefault null
review"approved" or "changes_requested" or "commented" or nulldefault null
urlstringrunIdstringcreatedAtdate-time
commentsarray of objectFields of
commentsiduuidbodystringrunIduuid or nullcreatedAtdate-timeauthorobjectFields of
authorkind"person" or "agent"iduuidnamestring
questionsarray of objectFields of
questionsiduuidrunIduuidquestionstringanswerstring or nullstate"waiting" or "answered" or "skipped" or "unanswered"askedAtdate-timeansweredAtdate-time or nullansweredBystring or null
PATCH /api/tasks/{id}
Changes the title, description, repository or status (open, review or done).
Path
iduuid required
Body
titlestring1 to 200 characters
bodystringup to 100,000 characters
repositorystring or nullup to 2,000 characters
status"open" or "review" or "done"
Answer 200
iduuidtitlestringagentobjectFields of
agentiduuidnamestringstatus"active" or "archived"
status"open" or "review" or "done"source"manual" or "jira" or "cron" or "webhook" or "chat" or "agent"repositorystring or nullrepositoryFromProjectbooleancreatedByobjectFields of
createdByiduuidnamestring
createdAtdate-timelatestRunobject or nullFields of
latestRuniduuidstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-time
projectobject or nullFields of
projectiduuidnamestring
changeRequestobject or nullFields of
changeRequeststate"open" or "draft" or "merged" or "closed" or nulldefault null
pipeline"none" or "running" or "success" or "failed" or nulldefault null
urlstring
bodystringexternalErrorstring or nullconnectionobject or nullFields of
connectioniduuidkind"github" or "gitlab" or "jira"projectobjectFields of
projectiduuidnamestring
parentobject or nullFields of
parentiduuidtitlestringagentstring
subtasksarray of objectFields of
subtasksiduuidtitlestringagentstringstatus"open" or "review" or "done"runStatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled" or null
runsarray of objectFields of
runsiduuidstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"startedAtdate-time or nullendedAtdate-time or nullerrorCodestring or nullsummarystring or nullseatobject or nullFields of
seatnamestring
createdAtdate-timeusdstring or null
changeRequestsarray of objectFields of
changeRequestsstate"open" or "draft" or "merged" or "closed" or nulldefault null
pipeline"none" or "running" or "success" or "failed" or nulldefault null
review"approved" or "changes_requested" or "commented" or nulldefault null
urlstringrunIdstringcreatedAtdate-time
commentsarray of objectFields of
commentsiduuidbodystringrunIduuid or nullcreatedAtdate-timeauthorobjectFields of
authorkind"person" or "agent"iduuidnamestring
questionsarray of objectFields of
questionsiduuidrunIduuidquestionstringanswerstring or nullstate"waiting" or "answered" or "skipped" or "unanswered"askedAtdate-timeansweredAtdate-time or nullansweredBystring or null
GET /api/tasks/{id}/changes
What the task changed: its runs' branches with their commits and size, and its change requests as the code host has them now.
Path
iduuid required
Answer 200
branchesarray of objectFields of
branchesnamestringcommitsarray of objectFields of
commitsshastringsubjectstring
additionsinteger or nulldeletionsinteger or nullfilesinteger or nullurlstring or null
changeRequestsarray of objectFields of
changeRequestsurlstringnumberinteger or nulltitlestring or nullstate"open" or "draft" or "merged" or "closed" or nulldefault null
pipeline"none" or "running" or "success" or "failed" or nulldefault null
problemstring or null
POST /api/tasks/{id}/run
Queues another run of the task, for a seat of the agent's owner.
Path
iduuid required
Answer 201
iduuidstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
POST /api/tasks/{id}/comments
Comments on a task, in markdown; with run true, also queues a run, which reads the comment (refused while one is going). The task's agent reads the thread in its next run.
Path
iduuid required
Body
bodystring required1 to 20,000 characters
runbooleandefault false
Answer 201
iduuidrunobject or nullFields of
runiduuidstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
Runs
What a run did: its transcript, artifacts and cost.
GET /api/runs/{id}/events
The transcript of a run after a seq, at most 1000 events.
Path
iduuid required
Query
all"true" or "false"An admin reads every run; default "false"
afterintegerdefault -1
Answer 200
eventsarray of anynextAfterinteger or null
POST /api/runs/{id}/cancel
Cancels a queued run, or asks the seat to stop a running one.
Path
iduuid required
Answer 200
status"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"cancelRequestedboolean
GET /api/runs
Runs the signed-in person may read, newest first.
Query
all"true" or "false"An admin reads every run; default "false"
agentuuidtaskuuidstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled" or "live"limitinteger1 to 100; default 50
beforedate-time
Answer 200
runsarray of objectFields of
runsiduuidstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"agentobjectFields of
agentiduuidnamestring
taskobject or nullFields of
taskiduuidtitlestringprojectIduuid or null
seatobject or nullFields of
seatiduuidnamestringownerobjectFields of
owneriduuidnamestring
startedByobjectFields of
startedBykind"user" or "cron" or "webhook" or "agent"userobject or nullFields of
useriduuidnamestring
startedAtdate-time or nullendedAtdate-time or nullerrorCodestring or nullcreatedAtdate-timecostobjectFields of
costusdstring or nulltokensinteger
nextBeforedate-time or null
GET /api/runs/{id}
A run with its artifacts and cost.
Path
iduuid required
Query
all"true" or "false"An admin reads every run; default "false"
Answer 200
iduuidstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"agentobjectFields of
agentiduuidnamestring
taskobject or nullFields of
taskiduuidtitlestringprojectIduuid or null
seatobject or nullFields of
seatiduuidnamestringownerobjectFields of
owneriduuidnamestring
startedByobjectFields of
startedBykind"user" or "cron" or "webhook" or "agent"userobject or nullFields of
useriduuidnamestring
startedAtdate-time or nullendedAtdate-time or nullerrorCodestring or nullcreatedAtdate-timelimitsobject or nullFields of
limitsmaxMinutesintegermaxTurnsintegermaxTokensinteger
cancelRequestedAtdate-time or nullsummarystring or nullartifactsarray of objectFields of
artifactsiduuidkind"branch" or "change_request" or "file" or "report"refstringmetaobjectcreatedAtdate-time
toolCallsarray of objectFields of
toolCallstoolstringagentIduuiddecision"allowed" or "pending" or "approved" or "denied"reasonstring or nulldecidedByobject or nullFields of
decidedByidstringnamestring
createdAtdate-timemembersarray of uuid optional
teamarray of objectFields of
teamkeystringagentIduuidnamestring
costobjectFields of
costrowsarray of objectFields of
rowsmodelstringtokensInintegertokensOutintegertokensCacheReadintegertokensCacheWriteintegerusdstring or null
totalUsdstring or nullunpricedboolean
GET /api/runs/{id}/stream
The transcript of a run as server-sent events, live until the run ends.
Path
iduuid required
Query
all"true" or "false"An admin reads every run; default "false"
afterintegerdefault -1
Answer
200.
Approvals
Tool calls waiting for their owner's decision, and agents' questions.
GET /api/approvals
Tool calls waiting for a decision on the person's agents, oldest first.
Answer 200
approvalsarray of objectFields of
approvalsiduuidtoolstringinputanyrunIduuidagentobjectFields of
agentiduuidnamestring
taskobject or nullFields of
taskiduuidtitlestringrepositorystring or null
createdAtdate-time
POST /api/tool-calls/{id}/approve
Lets a waiting tool call run; only the agent's owner decides. With always, the agent is not asked about that tool again.
Path
iduuid required
Body
alwaysboolean
Answer 200
decision"allowed" or "pending" or "approved" or "denied"reasonstring or null
POST /api/tool-calls/{id}/answer
Answers an agent's question (ask_owner); the agent reads the answer.
Path
iduuid required
Body
answerstring required1 to 4,000 characters
Answer 200
decision"allowed" or "pending" or "approved" or "denied"reasonstring or null
POST /api/tool-calls/{id}/deny
Refuses a waiting tool call; the agent reads the reason.
Path
iduuid required
Body
reasonstringup to 1,000 characters
Answer 200
decision"allowed" or "pending" or "approved" or "denied"reasonstring or null
Projects
Projects with their repositories, agents, knowledge and the services their runs need.
GET /api/projects
Every project, newest first.
Answer 200
projectsarray of objectFields of
projectsiduuidnamestringagentCountintegerconnectionCountintegercreatedByuuidcreatedAtdate-timeteamobject or nullFields of
teamiduuidnamestring
weekobjectFields of
weekrunsintegerendedintegerdoneintegermedianSecondsinteger or nullusdstring or nulldailyarray of integer
lastRunobject or nullFields of
lastRuniduuidstatus"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"atdate-timeagentobjectFields of
agentiduuidnamestring
taskobjectFields of
taskiduuidtitlestring
POST /api/projects
Creates a project.
Body
namestring required1 to 100 characters
descriptionstringup to 100,000 characters
goalsstringup to 100,000 characters
Answer 201
iduuidnamestringagentCountintegerconnectionCountintegercreatedByuuidcreatedAtdate-timeteamobject or nullFields of
teamiduuidnamestringleadobjectFields of
leadiduuidnamestring
intake"manual" or "auto"budgetobjectFields of
budgetusdPerMonthnumber or nullusdThisMonthnumber
triggersobjectFields of
triggersonPipelineFailedbooleanonReviewbooleanreviewerobject or nullFields of
revieweriduuidnamestring
descriptionstringgoalsstringrepositoriesarray of stringallowedHostsarray of stringenvironmentobject or nullFields of
environmentrepositorystringdevcontainerstring or nullservicesarray of objectFields of
servicesnamestringimagestringup to 255 characters
environmentobjectcommandarray of string optionalup to 64 items
volumesarray of objectup to 8 items
Fields of
volumesnamestringtargetstringup to 255 characters
problemsarray of stringreadAtdate-timehashstringapprovedboolean
agentsarray of objectFields of
agentsiduuidnamestringroleTitlestringstatus"active" or "archived"
connectionsarray of objectFields of
connectionsiduuidkind"github" or "gitlab" or "jira"hoststringnamespacestringaccountLoginstring or nullagentNamestring or null
weekobjectFields of
weekrunsintegerendedintegerdoneintegermedianSecondsinteger or nullusdstring or nulldailyarray of integer
GET /api/projects/{id}
A project with its agents and connections.
Path
iduuid required
Answer 200
iduuidnamestringagentCountintegerconnectionCountintegercreatedByuuidcreatedAtdate-timeteamobject or nullFields of
teamiduuidnamestringleadobjectFields of
leadiduuidnamestring
intake"manual" or "auto"budgetobjectFields of
budgetusdPerMonthnumber or nullusdThisMonthnumber
triggersobjectFields of
triggersonPipelineFailedbooleanonReviewbooleanreviewerobject or nullFields of
revieweriduuidnamestring
descriptionstringgoalsstringrepositoriesarray of stringallowedHostsarray of stringenvironmentobject or nullFields of
environmentrepositorystringdevcontainerstring or nullservicesarray of objectFields of
servicesnamestringimagestringup to 255 characters
environmentobjectcommandarray of string optionalup to 64 items
volumesarray of objectup to 8 items
Fields of
volumesnamestringtargetstringup to 255 characters
problemsarray of stringreadAtdate-timehashstringapprovedboolean
agentsarray of objectFields of
agentsiduuidnamestringroleTitlestringstatus"active" or "archived"
connectionsarray of objectFields of
connectionsiduuidkind"github" or "gitlab" or "jira"hoststringnamespacestringaccountLoginstring or nullagentNamestring or null
weekobjectFields of
weekrunsintegerendedintegerdoneintegermedianSecondsinteger or nullusdstring or nulldailyarray of integer
PATCH /api/projects/{id}
Changes a project. repositories replaces the list, main one first; each must fall under a code-host connection of the project. teamId names the team that takes the project's tasks (its agents join the project); intake auto has its lead take a new task at once; allowedHosts (an admin's) are what its runs in places on the server may reach.
Path
iduuid required
Body
namestring1 to 100 characters
descriptionstringup to 100,000 characters
goalsstringup to 100,000 characters
repositoriesarray of uriup to 20 items
allowedHostsarray of stringup to 100 items
teamIduuid or nullintake"manual" or "auto"usdPerMonthnumber or null0 to 1,000,000
onPipelineFailedbooleanonReviewbooleanreviewerAgentIduuid or null
Answer 200
iduuidnamestringagentCountintegerconnectionCountintegercreatedByuuidcreatedAtdate-timeteamobject or nullFields of
teamiduuidnamestringleadobjectFields of
leadiduuidnamestring
intake"manual" or "auto"budgetobjectFields of
budgetusdPerMonthnumber or nullusdThisMonthnumber
triggersobjectFields of
triggersonPipelineFailedbooleanonReviewbooleanreviewerobject or nullFields of
revieweriduuidnamestring
descriptionstringgoalsstringrepositoriesarray of stringallowedHostsarray of stringenvironmentobject or nullFields of
environmentrepositorystringdevcontainerstring or nullservicesarray of objectFields of
servicesnamestringimagestringup to 255 characters
environmentobjectcommandarray of string optionalup to 64 items
volumesarray of objectup to 8 items
Fields of
volumesnamestringtargetstringup to 255 characters
problemsarray of stringreadAtdate-timehashstringapprovedboolean
agentsarray of objectFields of
agentsiduuidnamestringroleTitlestringstatus"active" or "archived"
connectionsarray of objectFields of
connectionsiduuidkind"github" or "gitlab" or "jira"hoststringnamespacestringaccountLoginstring or nullagentNamestring or null
weekobjectFields of
weekrunsintegerendedintegerdoneintegermedianSecondsinteger or nullusdstring or nulldailyarray of integer
DELETE /api/projects/{id}
Deletes a project with its connections, knowledge and assignments; its tasks stay.
Path
iduuid required
Answer 204
null
GET /api/projects/{id}/refused-hosts
The hosts the project's runs in places asked for in the last 7 days and were refused, newest first; an admin's.
Path
iduuid required
Answer 200
hostsarray of objectFields of
hostshoststringportnumbercountnumberlastAtdate-time
POST /api/projects/{id}/environment
Reads the services the project's main repository asks for in its devcontainer (.devcontainer/devcontainer.json and the compose files it names) from its default branch. Only services that run an image as it is come through; what is left out is in problems. A changed list needs an admin's approval before places run it.
Path
iduuid required
Answer 200
iduuidnamestringagentCountintegerconnectionCountintegercreatedByuuidcreatedAtdate-timeteamobject or nullFields of
teamiduuidnamestringleadobjectFields of
leadiduuidnamestring
intake"manual" or "auto"budgetobjectFields of
budgetusdPerMonthnumber or nullusdThisMonthnumber
triggersobjectFields of
triggersonPipelineFailedbooleanonReviewbooleanreviewerobject or nullFields of
revieweriduuidnamestring
descriptionstringgoalsstringrepositoriesarray of stringallowedHostsarray of stringenvironmentobject or nullFields of
environmentrepositorystringdevcontainerstring or nullservicesarray of objectFields of
servicesnamestringimagestringup to 255 characters
environmentobjectcommandarray of string optionalup to 64 items
volumesarray of objectup to 8 items
Fields of
volumesnamestringtargetstringup to 255 characters
problemsarray of stringreadAtdate-timehashstringapprovedboolean
agentsarray of objectFields of
agentsiduuidnamestringroleTitlestringstatus"active" or "archived"
connectionsarray of objectFields of
connectionsiduuidkind"github" or "gitlab" or "jira"hoststringnamespacestringaccountLoginstring or nullagentNamestring or null
weekobjectFields of
weekrunsintegerendedintegerdoneintegermedianSecondsinteger or nullusdstring or nulldailyarray of integer
POST /api/projects/{id}/environment/approve
Lets the project's services run in people's places on the server: give the hash of the list you read, which is refused if the list has changed since. The images are the repository's, run on the company's server.
Path
iduuid required
Body
hashstring required
Answer 200
iduuidnamestringagentCountintegerconnectionCountintegercreatedByuuidcreatedAtdate-timeteamobject or nullFields of
teamiduuidnamestringleadobjectFields of
leadiduuidnamestring
intake"manual" or "auto"budgetobjectFields of
budgetusdPerMonthnumber or nullusdThisMonthnumber
triggersobjectFields of
triggersonPipelineFailedbooleanonReviewbooleanreviewerobject or nullFields of
revieweriduuidnamestring
descriptionstringgoalsstringrepositoriesarray of stringallowedHostsarray of stringenvironmentobject or nullFields of
environmentrepositorystringdevcontainerstring or nullservicesarray of objectFields of
servicesnamestringimagestringup to 255 characters
environmentobjectcommandarray of string optionalup to 64 items
volumesarray of objectup to 8 items
Fields of
volumesnamestringtargetstringup to 255 characters
problemsarray of stringreadAtdate-timehashstringapprovedboolean
agentsarray of objectFields of
agentsiduuidnamestringroleTitlestringstatus"active" or "archived"
connectionsarray of objectFields of
connectionsiduuidkind"github" or "gitlab" or "jira"hoststringnamespacestringaccountLoginstring or nullagentNamestring or null
weekobjectFields of
weekrunsintegerendedintegerdoneintegermedianSecondsinteger or nullusdstring or nulldailyarray of integer
PUT /api/projects/{id}/agents/{agentId}
Assigns an agent to a project.
Path
iduuid requiredagentIduuid required
Answer
200.
DELETE /api/projects/{id}/agents/{agentId}
Takes an agent off a project.
Path
iduuid requiredagentIduuid required
Answer
200.
GET /api/projects/{id}/knowledge
A project's knowledge sources, with when each last synced.
Path
iduuid required
Answer 200
sourcesarray of objectFields of
sourcesiduuidrepositorystringpathsarray of stringlastSyncAtdate-time or nulllastSyncErrorstring or nulldocumentsinteger
POST /api/projects/{id}/knowledge
Adds markdown of a connected repository to the project, and syncs it.
Path
iduuid required
Body
repositoryuri requiredup to 500 characters
pathsarray of string requiredup to 20 items
Answer 201
iduuidrepositorystringpathsarray of stringlastSyncAtdate-time or nulllastSyncErrorstring or nulldocumentsinteger
POST /api/knowledge/{id}/sync
Syncs a source now; a failure is in the answer, as lastSyncError.
Path
iduuid required
Answer 200
iduuidrepositorystringpathsarray of stringlastSyncAtdate-time or nulllastSyncErrorstring or nulldocumentsinteger
DELETE /api/knowledge/{id}
Removes a source and its documents.
Path
iduuid required
Answer
200.
Teams
A lead with members, and the order they work in.
GET /api/teams
Lists the teams whose leads the person may see.
Answer 200
teamsarray of objectFields of
teamsiduuidnamestringmode"auto" or "manual"leadobjectFields of
leadiduuidnamestringroleTitlestringstatus"active" or "archived"
membersarray of objectFields of
membersiduuidnamestringroleTitlestringstatus"active" or "archived"
stepsarray of objectup to 10 items
Fields of
stepsagentsarray of uuidup to 10 items
notestringup to 1,000 characters
POST /api/teams
Creates a team: its lead, whose runs it works in, and members from the lead's owner's active agents; an agent leads one team at most.
Body
namestring required1 to 100 characters
leadIduuid requiredmode"auto" or "manual"default "auto"
membersarray of uuidup to 10 items; default []
stepsarray of objectup to 10 items; default []
Fields of
stepsagentsarray of uuid requiredup to 10 items
notestring requiredup to 1,000 characters
Answer 201
iduuidnamestringmode"auto" or "manual"leadobjectFields of
leadiduuidnamestringroleTitlestringstatus"active" or "archived"
membersarray of objectFields of
membersiduuidnamestringroleTitlestringstatus"active" or "archived"
stepsarray of objectup to 10 items
Fields of
stepsagentsarray of uuidup to 10 items
notestringup to 1,000 characters
GET /api/teams/{id}
One team.
Path
iduuid required
Answer 200
iduuidnamestringmode"auto" or "manual"leadobjectFields of
leadiduuidnamestringroleTitlestringstatus"active" or "archived"
membersarray of objectFields of
membersiduuidnamestringroleTitlestringstatus"active" or "archived"
stepsarray of objectup to 10 items
Fields of
stepsagentsarray of uuidup to 10 items
notestringup to 1,000 characters
PATCH /api/teams/{id}
Renames a team, or gives it another lead, mode, steps or members (all of them, in order: add an agent by sending the list with it).
Path
iduuid required
Body
namestring1 to 100 characters
leadIduuidmode"auto" or "manual"membersarray of uuidup to 10 items
stepsarray of objectup to 10 items
Fields of
stepsagentsarray of uuid requiredup to 10 items
notestring requiredup to 1,000 characters
Answer 200
iduuidnamestringmode"auto" or "manual"leadobjectFields of
leadiduuidnamestringroleTitlestringstatus"active" or "archived"
membersarray of objectFields of
membersiduuidnamestringroleTitlestringstatus"active" or "archived"
stepsarray of objectup to 10 items
Fields of
stepsagentsarray of uuidup to 10 items
notestringup to 1,000 characters
DELETE /api/teams/{id}
Removes a team; its agents stay.
Path
iduuid required
Answer 204
null
POST /api/teams/{id}/duplicate
Copies a team, named "<name> (copy)", with copies of its agents owned by the person copying: their configuration, not their memory, tasks or runs.
Path
iduuid required
Answer 201
iduuidnamestringmode"auto" or "manual"leadobjectFields of
leadiduuidnamestringroleTitlestringstatus"active" or "archived"
membersarray of objectFields of
membersiduuidnamestringroleTitlestringstatus"active" or "archived"
stepsarray of objectup to 10 items
Fields of
stepsagentsarray of uuidup to 10 items
notestringup to 1,000 characters
Library
Skills and MCP servers people give their agents.
GET /api/library/skills
The newest version of every skill the person may use.
Answer 200
skillsarray of objectFields of
skillsiduuidnamestringdescriptionstringversionintegerownerobject or nullFields of
owneriduuidnamestring
visibility"org" or "private"createdAtdate-time
POST /api/library/skills
Adds a skill for the person, from its SKILL.md.
Body
contentstring required1 to 100,000 characters
Answer 201
iduuidnamestringdescriptionstringversionintegerownerobject or nullFields of
owneriduuidnamestring
visibility"org" or "private"createdAtdate-timecontentstring
GET /api/library/skills/{id}
One version of a skill, with its SKILL.md.
Path
iduuid required
Answer 200
iduuidnamestringdescriptionstringversionintegerownerobject or nullFields of
owneriduuidnamestring
visibility"org" or "private"createdAtdate-timecontentstring
DELETE /api/library/skills/{id}
Deletes a skill with every version: its author, or an admin once it is shared.
Path
iduuid required
Answer 204
null
GET /api/library/skills/{id}/agents
The person's agents that have the skill, at any version of it.
Path
iduuid required
Answer 200
agentsarray of objectFields of
agentsiduuidnamestring
POST /api/library/skills/{id}/versions
Adds a version to the person's own skill; agents keep theirs until moved on.
Path
iduuid required
Body
contentstring required1 to 100,000 characters
Answer 201
iduuidnamestringdescriptionstringversionintegerownerobject or nullFields of
owneriduuidnamestring
visibility"org" or "private"createdAtdate-timecontentstring
GET /api/library/mcp
The MCP servers the person may give their agents.
Answer 200
serversarray of objectFields of
serversiduuidnamestringdescriptionstringurlstringhasAuthorizationbooleanauth"header" or "oauth"signedInbooleantoolsarray of objectFields of
toolsnamestringtitlestringdescriptionstring
checkedAtdate-timeownerobject or nullFields of
owneriduuidnamestring
visibility"org" or "private"
POST /api/library/mcp
Adds an MCP server for the person, once it answers with its tools; one that signs in with OAuth is listed once someone signs in.
Body
namestring requiredIts tools reach the agent as <name>__<tool>
urluri requiredup to 500 characters
descriptionstringup to 500 characters
auth"header" or "oauth"default "header"
authorizationstring1 to 2,000 characters
Answer 201
iduuidnamestringdescriptionstringurlstringhasAuthorizationbooleanauth"header" or "oauth"signedInbooleantoolsarray of objectFields of
toolsnamestringtitlestringdescriptionstring
checkedAtdate-timeownerobject or nullFields of
owneriduuidnamestring
visibility"org" or "private"
GET /api/library/mcp/{id}/agents
The person's agents that have the server.
Path
iduuid required
Answer 200
agentsarray of objectFields of
agentsiduuidnamestring
PATCH /api/library/mcp/{id}
Changes the person's own server; null removes its Authorization header.
Path
iduuid required
Body
urluriup to 500 characters
descriptionstringup to 500 characters
authorizationstring or null1 to 2,000 characters
Answer 200
iduuidnamestringdescriptionstringurlstringhasAuthorizationbooleanauth"header" or "oauth"signedInbooleantoolsarray of objectFields of
toolsnamestringtitlestringdescriptionstring
checkedAtdate-timeownerobject or nullFields of
owneriduuidnamestring
visibility"org" or "private"
DELETE /api/library/mcp/{id}
Deletes a server: its author, or an admin once it is shared; agents lose it from their next run.
Path
iduuid required
Answer 204
null
POST /api/library/mcp/{id}/check
Asks the server for its tools again and keeps the answer.
Path
iduuid required
Answer 200
iduuidnamestringdescriptionstringurlstringhasAuthorizationbooleanauth"header" or "oauth"signedInbooleantoolsarray of objectFields of
toolsnamestringtitlestringdescriptionstring
checkedAtdate-timeownerobject or nullFields of
owneriduuidnamestring
visibility"org" or "private"
POST /api/library/mcp/{id}/sign-in
Starts the person’s OAuth sign-in to a server: the address to open in the browser.
Path
iduuid required
Answer 200
urlstring
DELETE /api/library/mcp/{id}/sign-in
Signs the person out of a server; their agents lose its tools until they sign in.
Path
iduuid required
Answer 204
null
GET /api/library/mcp/oauth/callback
Where the browser comes back from an OAuth sign-in.
No sign-in.
Query
codestringup to 4,000 characters
statestringup to 200 characters
errorstringup to 200 characters
error_descriptionstringup to 500 characters
Answer
200.
Connections
GitLab, GitHub and Jira Data Center, with the webhooks they send.
GET /api/connections
Every connection to a code host, newest first.
Answer 200
connectionsarray of objectFields of
connectionsiduuidprojectobjectFields of
projectiduuidnamestring
agentobject or nullFields of
agentiduuidnamestring
kind"github" or "gitlab" or "jira"configobjecthoststringnamespacestringaccountLoginstring or nulllastTestedAtdate-time or nullsyncedAtdate-time or nullsyncErrorstring or nullcreatedAtdate-time
POST /api/connections
Connects a project to a code host with a token.
Body
projectIduuid requiredagentIduuidconfigany requiredtokenstring required1 to 500 characters
Answer 201
iduuidprojectobjectFields of
projectiduuidnamestring
agentobject or nullFields of
agentiduuidnamestring
kind"github" or "gitlab" or "jira"configobjecthoststringnamespacestringaccountLoginstring or nulllastTestedAtdate-time or nullsyncedAtdate-time or nullsyncErrorstring or nullcreatedAtdate-time
GET /api/connections/{id}
One connection.
Path
iduuid required
Answer 200
iduuidprojectobjectFields of
projectiduuidnamestring
agentobject or nullFields of
agentiduuidnamestring
kind"github" or "gitlab" or "jira"configobjecthoststringnamespacestringaccountLoginstring or nulllastTestedAtdate-time or nullsyncedAtdate-time or nullsyncErrorstring or nullcreatedAtdate-time
PATCH /api/connections/{id}
Changes where a connection reaches, or replaces its token.
Path
iduuid required
Body
configanytokenstring1 to 500 characters
Answer 200
iduuidprojectobjectFields of
projectiduuidnamestring
agentobject or nullFields of
agentiduuidnamestring
kind"github" or "gitlab" or "jira"configobjecthoststringnamespacestringaccountLoginstring or nulllastTestedAtdate-time or nullsyncedAtdate-time or nullsyncErrorstring or nullcreatedAtdate-time
DELETE /api/connections/{id}
Removes a connection and its token.
Path
iduuid required
Answer
200.
POST /api/connections/{id}/test
Asks the host whose token this is.
Path
iduuid required
Answer 200
loginstringtestedAtdate-time
POST /api/connections/{id}/sync
Polls a Jira connection now, without waiting for the interval.
Path
iduuid required
Answer 200
importednumberupdatednumber
GET /api/connections/{id}/webhook
The URL and secret for the host's webhook settings.
Path
iduuid required
Answer 200
urlurisecretstring
POST /webhooks/{kind}/{connectionId}
A webhook delivery of GitHub or GitLab, signed with the connection’s secret.
No sign-in.
Path
kind"github" or "gitlab" requiredconnectionIduuid required
Answer 200
status"received" or "ignored" or "duplicate"
Models
Model connections for agents that run on the server.
GET /api/model-connections
Every model connection, by name, with the models of its last check.
Answer 200
connectionsarray of objectFields of
connectionsiduuidnamestringkind"anthropic" or "openai" or "gateway"baseUrlstringmodelsarray of objectFields of
modelsidstringengine"claude-code" or "codex"
checkedAtdate-time or nullcreatedAtdate-time
POST /api/model-connections
Adds a model connection once its key lists its models.
Body
namestring required1 to 100 characters
kind"anthropic" or "openai" or "gateway" requiredbaseUrluriup to 500 characters
keystring required1 to 4,096 characters
Answer 201
iduuidnamestringkind"anthropic" or "openai" or "gateway"baseUrlstringmodelsarray of objectFields of
modelsidstringengine"claude-code" or "codex"
checkedAtdate-time or nullcreatedAtdate-time
GET /api/models
The models agents may work with on the server, by connection.
Answer 200
connectionsarray of objectFields of
connectionsiduuidnamestringmodelsarray of objectFields of
modelsidstringengine"claude-code" or "codex"
PATCH /api/model-connections/{id}
Renames a model connection, or changes its address or key.
Path
iduuid required
Body
namestring1 to 100 characters
baseUrluriup to 500 characters
keystring1 to 4,096 characters
Answer 200
iduuidnamestringkind"anthropic" or "openai" or "gateway"baseUrlstringmodelsarray of objectFields of
modelsidstringengine"claude-code" or "codex"
checkedAtdate-time or nullcreatedAtdate-time
DELETE /api/model-connections/{id}
Removes a model connection and its key.
Path
iduuid required
Answer
200.
POST /api/model-connections/{id}/check
Reads the models of a connection again.
Path
iduuid required
Answer 200
iduuidnamestringkind"anthropic" or "openai" or "gateway"baseUrlstringmodelsarray of objectFields of
modelsidstringengine"claude-code" or "codex"
checkedAtdate-time or nullcreatedAtdate-time
Computers
People's computers that run agents, connected with a pairing code.
POST /api/seats/pairing-codes
Creates a code that connects a computer.
Answer 201
codestringexpiresAtdate-timecommandstringwindowsCommandstring or nullcheckoutboolean
GET /api/seats
The signed-in user's seats; every seat for an admin.
Answer 200
An array of:
iduuidnamestringownerobjectFields of
owneriduuidnamestring
kind"subscription-laptop" or "api-server" or "local-model" or "subscription-server"status"active" or "revoked"lastSeenAtdate-time or nullidleMinutesinteger5 to 120
activeRunobject or nullFields of
activeRuniduuidagentNamestringstartedAtdate-time or null
updateCommandstring or nullsignedOutarray of "claude-code" or "codex"platformstring or nullsandboxobjectFields of
sandboxnonebooleanallowedAtdate-time or null
PATCH /api/seats/{id}
Changes a seat's name or its idle time.
Path
iduuid required
Body
namestring1 to 100 characters
idleMinutesinteger5 to 120
Answer 200
iduuidnamestringownerobjectFields of
owneriduuidnamestring
kind"subscription-laptop" or "api-server" or "local-model" or "subscription-server"status"active" or "revoked"lastSeenAtdate-time or nullidleMinutesinteger5 to 120
activeRunobject or nullFields of
activeRuniduuidagentNamestringstartedAtdate-time or null
updateCommandstring or nullsignedOutarray of "claude-code" or "codex"platformstring or nullsandboxobjectFields of
sandboxnonebooleanallowedAtdate-time or null
DELETE /api/seats/{id}
Revokes a seat and stops its run.
Path
iduuid required
Answer
200.
PUT /api/seats/{id}/sandbox
Allows a Windows computer to run the agent's commands without a sandbox, or takes that back.
Path
iduuid required
Body
allowedboolean required
Answer 200
iduuidnamestringownerobjectFields of
owneriduuidnamestring
kind"subscription-laptop" or "api-server" or "local-model" or "subscription-server"status"active" or "revoked"lastSeenAtdate-time or nullidleMinutesinteger5 to 120
activeRunobject or nullFields of
activeRuniduuidagentNamestringstartedAtdate-time or null
updateCommandstring or nullsignedOutarray of "claude-code" or "codex"platformstring or nullsandboxobjectFields of
sandboxnonebooleanallowedAtdate-time or null
POST /api/seats/{id}/remove
Takes a revoked seat off the list; its runs still name it.
Path
iduuid required
Answer 204
null
Places
The signed-in person's place on the server, where their agents run.
GET /api/me/place
The signed-in person's place on the server.
Answer 200
availablebooleancomputersbooleanplaceobject or nullFields of
placeseatIduuid or nullstate"none" or "asleep" or "awake" or "unknown"signedOutarray of stringlastSeenAtdate-time or nullagentsarray of objectFields of
agentsiduuidnamestring
diskobject or nullFields of
diskusedBytesnumberlimitBytesnumber
POST /api/me/place
Makes a place on the server for the signed-in person, and connects it.
Answer 201
availablebooleancomputersbooleanplaceobject or nullFields of
placeseatIduuid or nullstate"none" or "asleep" or "awake" or "unknown"signedOutarray of stringlastSeenAtdate-time or nullagentsarray of objectFields of
agentsiduuidnamestring
diskobject or nullFields of
diskusedBytesnumberlimitBytesnumber
DELETE /api/me/place
Deletes the signed-in person's place, its sign-in and working folders with it.
Answer 204
null
POST /api/me/place/wake
Wakes the signed-in person's place.
Answer 200
availablebooleancomputersbooleanplaceobject or nullFields of
placeseatIduuid or nullstate"none" or "asleep" or "awake" or "unknown"signedOutarray of stringlastSeenAtdate-time or nullagentsarray of objectFields of
agentsiduuidnamestring
diskobject or nullFields of
diskusedBytesnumberlimitBytesnumber
POST /api/me/place/sleep
Puts the signed-in person's place to sleep.
Answer 200
availablebooleancomputersbooleanplaceobject or nullFields of
placeseatIduuid or nullstate"none" or "asleep" or "awake" or "unknown"signedOutarray of stringlastSeenAtdate-time or nullagentsarray of objectFields of
agentsiduuidnamestring
diskobject or nullFields of
diskusedBytesnumberlimitBytesnumber
DELETE /api/me/place/folders/{agentId}
Empties an agent's working folders in the signed-in person's place.
Path
agentIduuid required
Answer 204
null
You
The signed-in person: their name, API tokens and notifications.
GET /api/me
The signed-in person.
Answer 200
iduuidnamestringemailstringrole"admin" or "member"
PATCH /api/me
Renames the signed-in person or changes their email.
Body
namestring1 to 100 characters
emailemailup to 254 characters
currentPasswordstringup to 128 characters
Answer 200
iduuidnamestringemailstringrole"admin" or "member"
GET /api/me/two-factor
Whether the signed-in person's password sign-in asks for a code.
Answer 200
availablebooleanenabledboolean
POST /api/me/presence
Marks the signed-in person as present, for their place on the server.
Answer 204
null
GET /api/me/tokens
The person's own tokens that are not revoked, expired ones too, newest first.
Answer 200
tokensarray of objectFields of
tokensiduuidnamestring1 to 80 characters
scope"read" or "write"createdAtdate-timeexpiresAtdate-time or nulllastUsedAtdate-time or null
POST /api/me/tokens
Creates a token that acts as the person; the token is in this answer only.
Body
namestring required1 to 80 characters
scope"read" or "write"read: the token passes only requests that read; default "write"
expiresInDaysinteger or nullDays until the token stops working, up to a year; null never expires; 1 to 365; default 30
Answer 201
iduuidnamestring1 to 80 characters
scope"read" or "write"createdAtdate-timeexpiresAtdate-time or nulllastUsedAtdate-time or nulltokenstring
DELETE /api/me/tokens/{id}
Revokes a token; whatever holds it is signed out at once.
Path
iduuid required
Answer 204
null
GET /api/me/push
The server's public VAPID key, for a browser to subscribe with.
Answer 200
publicKeystring
PUT /api/me/push/subscriptions
Turns notifications on for this browser: its push subscription, as it is.
Body
endpointstring requiredup to 2,048 characters
keysobject requiredFields of
keysp256dhstring requiredauthstring required
Answer 204
null
DELETE /api/me/push/subscriptions
Turns notifications off for this browser.
Body
endpointstring requiredup to 2,048 characters
Answer 204
null
POST /api/me/push/test
Sends a test notification to the person's devices; answers how many took it.
Answer 200
sentinteger
People
Accounts, invitations and handing work over.
GET /api/users
Everyone with an account.
Answer 200
usersarray of objectFields of
usersiduuidnamestringemailstringrole"admin" or "member"disabledAtstring or nullcreatedAtstring
GET /api/people
The names of the people who can be given an agent: everyone not disabled.
Answer 200
peoplearray of objectFields of
peopleiduuidnamestring
POST /api/users/{id}/transfer-agents
Transfers everything a person owns to a successor, for good; what they had for a time goes back to its owner.
Path
iduuid required
Body
touuid required
Answer 200
transferredarray of objectFields of
transferrediduuidnamestring
returnedarray of objectFields of
returnediduuidnamestring
toobjectFields of
toiduuidnamestring
PATCH /api/users/{id}
Disables or enables a person; disabling signs them out everywhere.
Path
iduuid required
Body
disabledboolean required
Answer 200
iduuidnamestringemailstringrole"admin" or "member"disabledAtstring or nullcreatedAtstring
POST /api/invitations
Creates an invitation link; the link is in this answer only.
Body
role"admin" or "member"default "member"
emailemailup to 254 characters
Answer 201
iduuidurlstringexpiresAtstring
GET /api/invitations
Invitations that can still be accepted.
Answer 200
invitationsarray of objectFields of
invitationsiduuidrole"admin" or "member"emailstring or nullinvitedBystringcreatedAtstringexpiresAtstring
DELETE /api/invitations/{id}
Revokes an invitation.
Path
iduuid required
Answer
200.
GET /api/invitations/{token}
Whether an invitation link can still be used, and for which role.
No sign-in.
Path
tokenstring requiredup to 100 characters
Answer 200
validbooleanreason"unknown" or "expired" or "revoked" or "accepted" optionalrole"admin" or "member" optionalemailstring or null optionalinvitedBystring optionalorgNamestring optional
POST /api/invitations/{token}/accept
Creates the account an invitation is for, and signs the person in.
No sign-in.
Path
tokenstring requiredup to 100 characters
Body
namestring required1 to 100 characters
emailemail requiredup to 254 characters
passwordstring required12 to 128 characters
Answer 201
iduuidnamestringemailstringrole"admin" or "member"
DELETE /api/users/{id}/place
Deletes a person's place on the server, its sign-in and working folders with it; an admin's.
Path
iduuid required
Answer 204
null
Administration
Logs, the license, the version and the first-run setup.
GET /api/setup
Whether the setup is complete, and whether people can sign in with Keycloak and with a password.
No sign-in.
Answer 200
completedbooleankeycloakbooleanpasswordboolean
POST /api/setup
Completes the setup with the setup code from the server's log: the company and its first admin, who is signed in.
No sign-in.
Body
codestring requiredup to 64 characters
orgNamestring required1 to 100 characters
baseUrluriadminobject requiredFields of
adminnamestring required1 to 100 characters
emailemail requiredup to 254 characters
passwordstring required12 to 128 characters
Answer 201
iduuidnamestringemailstringrole"admin" or "member"
GET /api/admin/logs
Log lines of the server and the workers, newest first: from a level up, by source, run, trace or text.
Query
level"trace" or "debug" or "info" or "warn" or "error" or "fatal"source"server" or "worker"runuuidtracestringup to 64 characters
qstringup to 200 characters
beforeintegerafterintegerlimitinteger1 to 500; default 100
Answer 200
entriesarray of objectFields of
entriesidnumberatdate-timelevelnumbersource"server" or "worker"messagestringcontextany or nulltraceIdstring or nullrunIduuid or nullseatIduuid or nullspanstring or nulldurationMsnumber or null
nextBeforenumber or null
GET /api/admin/logs/traces/{id}
A trace's lines in order: the request, the calls it made out and what it logged.
Path
idstring required1 to 64 characters
Answer 200
traceIdstringentriesarray of objectFields of
entriesidnumberatdate-timelevelnumbersource"server" or "worker"messagestringcontextany or nulltraceIdstring or nullrunIduuid or nullseatIduuid or nullspanstring or nulldurationMsnumber or null
GET /api/admin/logs/level
The server's log level now.
Answer 200
level"trace" or "debug" or "info" or "warn" or "error" or "fatal"
PUT /api/admin/logs/level
Sets the server's log level until it restarts, when AGENTOME_LOG_LEVEL holds again.
Body
level"trace" or "debug" or "info" or "warn" or "error" or "fatal" required
Answer 200
level"trace" or "debug" or "info" or "warn" or "error" or "fatal"
GET /api/license
The license: Free or Enterprise, whom a key is for and until when, the agents, where the installation is over Free, and whether it is read-only.
Answer 200
status"free" or "valid" or "grace" or "read_only"enterprisebooleaninstallationIdstringidstring or nullcompanystring or nullexpiresAtdate-time or nullgraceEndsAtdate-time or nullagentsobjectFields of
agentslimitinteger or nullactiveintegerpeakinteger
overarray of "agents" or "teams" or "server_agents" or "budgets"
PUT /api/admin/license
Puts a new license key in place; it works at once, without a restart.
Body
keystring required1 to 4,000 characters
Answer 200
status"free" or "valid" or "grace" or "read_only"enterprisebooleaninstallationIdstringidstring or nullcompanystring or nullexpiresAtdate-time or nullgraceEndsAtdate-time or nullagentsobjectFields of
agentslimitinteger or nullactiveintegerpeakinteger
overarray of "agents" or "teams" or "server_agents" or "budgets"
GET /api/admin/version
The release and commit this server was built from, null for a development build, and whether Admin looks for a newer release.
Answer 200
versionstring or nullcommitstring or nullupdateCheckboolean
Health
For load balancers and monitoring; no sign-in.
GET /health
Answers while the process is alive.
No sign-in.
Answer 200
status"ok"
GET /ready
Answers when the database does.
No sign-in.
Answer 200
status"ok"
Worker
What a computer's worker calls with its seat's or its run's token. Listed so the whole API is here; a script has no use for it.
POST /api/seats/pair
Turns a pairing code into a seat and its token.
No sign-in.
Body
codestring requiredup to 64 characters
namestring required1 to 100 characters
kind"subscription-laptop" or "api-server" or "local-model" or "subscription-server" requiredenginesarray of "claude-code" or "codex" requiredup to 8 items
capabilitiesobjectdefault {}
Fields of
capabilitiesdockerbooleansandboxboolean
Answer 201
seatIduuidtokenstring
GET /api/seats/claim
Waits up to `wait` seconds for a run this seat may take.
With a seat’s or a run’s token.
Query
waitinteger0 to 25; default 25
enginesstringup to 200 characters
signedOutstringup to 200 characters
workerstringplatformstring
Answer 200
runobjectFields of
runiduuidtokenstringlimitsobjectFields of
limitsmaxMinutesintegermaxTurnsintegermaxTokensinteger
agentobjectFields of
agentiduuidnamestringroleTitlestringinstructionsstringengine"claude-code" or "codex"modelPrefstring or nullskillsarray of objectFields of
skillsnamestringversionintegercontentstring
memoryDocumentsarray of objectFields of
memoryDocumentspathstringversionintegercontentstring
teamobject optionalFields of
teammode"auto" or "manual"membersarray of objectFields of
memberskeystringagentIduuidnamestringdescriptionstringpromptstringmodelPrefstring or nulltokenstringskillsarray of objectFields of
skillsnamestringversionintegercontentstring
memoryDocumentsarray of objectFields of
memoryDocumentspathstringversionintegercontentstring
stepsarray of objectFields of
stepsmembersarray of stringnotestring
taskobject or nullFields of
taskiduuidtitlestringbodystringrepositorystring or null
modelobject optionalFields of
modelkind"anthropic" or "openai" or "gateway"baseUrlstringkeystring
workspaceobjectFields of
workspacemcpobjectFields of
mcpurlstring
gitobject optionalFields of
giturlstringusernamestringpasswordstring
servicesarray of string optionalprofileobjectFields of
profileclaudeMdstringprojectMdstring optionalsettingsobjectFields of
settingspermissionMode"acceptEdits"allowedToolsarray of stringsandboxobjectFields of
sandboxenabledbooleanfailIfUnavailablebooleanautoAllowBashIfSandboxedbooleanallowUnsandboxedCommandsfalsenetworkobjectFields of
networkallowedDomainsarray of stringstrictAllowlisttrueallowLocalBindingtrue optional
POST /api/seats/logs
Stores a batch of the worker's own log lines under its seat.
With a seat’s or a run’s token.
Body
linesarray of object requiredup to 500 items
Fields of
linesatdate-time requiredlevel"info" or "warn" or "error" requiredmessagestring requiredup to 4,000 characters
runIduuid
Answer 204
null
POST /api/runs/{id}/events
Appends a batch of run events; a batch sent again is ignored by seq.
With a seat’s or a run’s token.
Path
iduuid required
Body
An array of:
seqinteger requiredtypestring required1 to 64 characters
payloadobject requiredatdate-time required
Answer 200
acceptedintegercancelRequestedboolean
POST /api/runs/{id}/heartbeat
Keeps a run alive and tells the seat whether to stop.
With a seat’s or a run’s token.
Path
iduuid required
Answer 200
cancelRequestedbooleanwaitedMsinteger
POST /api/runs/{id}/finish
Ends a run with its summary, artifacts and usage.
With a seat’s or a run’s token.
Path
iduuid required
Body
status"done" or "failed" or "cancelled" requiredsummarystringup to 20,000 characters
errorCodestring1 to 64 characters
artifactsarray of objectup to 100 items; default []
Fields of
artifactskind"branch" or "file" or "report" requiredrefstring required1 to 2,000 characters
metaobjectdefault {}
usagearray of objectup to 100 items; default []
Fields of
usageproviderstring required1 to 64 characters
modelstring required1 to 200 characters
tokensIninteger requiredtokensOutinteger requiredtokensCacheReadinteger requiredtokensCacheWriteinteger requiredtokensCacheWrite1hintegerdefault 0
sourcestring required1 to 64 characters
Answer 200
status"queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
PUT /api/runs/{id}/container
Makes a place's run its own container: the place's worker asks, by its seat.
With a seat’s or a run’s token.
Path
iduuid required
Body
folderstringup to 200 characters
Answer 200
cliobjectFields of
clihoststring1 to 253 characters
portinteger1 to 65,535
keystring32 to 128 characters
sandboxobjectFields of
sandboxhoststring1 to 253 characters
portinteger1 to 65,535
keystring32 to 128 characters
dockerboolean optionalcliTokenstring
DELETE /api/runs/{id}/container
Deletes a place's run's container and what runs in it: the place's worker asks.
With a seat’s or a run’s token.
Path
iduuid required
Answer 204
null