Agentome GitHub
Contents

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

  • templates array of object
    Fields of templates
    • id uuid
    • name string
    • version integer
    • description string
    • roleTitle string
    • modelPref string 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

  • agents array of object
    Fields of agents
    • id uuid
    • name string
    • roleTitle string
    • status "active" or "archived"
    • owner object
      Fields of owner
      • id uuid
      • name string
    • lastRun object or null
      Fields of lastRun
      • id uuid
      • taskId uuid or null
      • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
      • at date-time
      • task object or null
        Fields of task
        • title string
        • project string or null
    • createdAt date-time
    • modelPref string or null
    • week object
      Fields of week
      • runs integer
      • usd string or null
      • ended integer
      • done integer
      • medianSeconds integer or null
      • daily array of integer

        up to 7 items

    • month object
      Fields of month
      • accepted integer
      • handed integer
      • medianUsd string or null

POST /api/agents

Creates an agent, blank or from a role template, owned by the person.

Body

  • name string required

    1 to 100 characters

  • roleTitle string

    up to 200 characters

  • templateId uuid

Answer 201

  • id uuid
  • name string
  • roleTitle string
  • status "active" or "archived"
  • owner object
    Fields of owner
    • id uuid
    • name string
  • lastRun object or null
    Fields of lastRun
    • id uuid
    • taskId uuid or null
    • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
    • at date-time
    • task object or null
      Fields of task
      • title string
      • project string or null
  • createdAt date-time
  • instructions string
  • engine "claude-code" or "codex"
  • modelPref string or null
  • runsOn "laptop" or "server"
  • modelConnection object or null
    Fields of modelConnection
    • id uuid
    • name string
  • serverShell boolean
  • budget object or null
    Fields of budget
    • maxMinutes integer optional
    • maxTurns integer optional
    • maxTokens integer optional
    • usdPerMonth number optional

      0 to 1,000,000

  • runDefaults object
    Fields of runDefaults
    • maxMinutes integer
    • maxTurns integer
    • maxTokens integer
  • copiedFromAgentId uuid or null
  • template object or null
    Fields of template
    • id uuid
    • name string
    • version integer
  • seat object or null
    Fields of seat
    • id uuid
    • name string
    • busy boolean
    • lastSeenAt date-time or null
  • people array of object
    Fields of people
    • id uuid
    • name string
    • level "owner"
    • validFrom date-time or null
    • validUntil date-time or null
  • projects array of object
    Fields of projects
    • id uuid
    • name string
    • hosts array of "github" or "gitlab" or "jira"
    • repositories array of string
  • tools array of object
    Fields of tools
    • connector string
    • name string
    • title string
    • policy "allow" or "ask" or "deny"
  • skills array of object
    Fields of skills
    • id uuid
    • name string
    • version string
    • privateTo string optional
  • mcpServers array of object
    Fields of mcpServers
    • id uuid
    • name string
    • privateTo string optional
  • memoryDocuments integer
  • spend object
    Fields of spend
    • usdThisMonth number
    • limit number or null
    • reached boolean
    • resumed boolean

GET /api/agents/{id}

Everything the editor and the agent sheet show.

Path

  • id uuid required

Answer 200

  • id uuid
  • name string
  • roleTitle string
  • status "active" or "archived"
  • owner object
    Fields of owner
    • id uuid
    • name string
  • lastRun object or null
    Fields of lastRun
    • id uuid
    • taskId uuid or null
    • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
    • at date-time
    • task object or null
      Fields of task
      • title string
      • project string or null
  • createdAt date-time
  • instructions string
  • engine "claude-code" or "codex"
  • modelPref string or null
  • runsOn "laptop" or "server"
  • modelConnection object or null
    Fields of modelConnection
    • id uuid
    • name string
  • serverShell boolean
  • budget object or null
    Fields of budget
    • maxMinutes integer optional
    • maxTurns integer optional
    • maxTokens integer optional
    • usdPerMonth number optional

      0 to 1,000,000

  • runDefaults object
    Fields of runDefaults
    • maxMinutes integer
    • maxTurns integer
    • maxTokens integer
  • copiedFromAgentId uuid or null
  • template object or null
    Fields of template
    • id uuid
    • name string
    • version integer
  • seat object or null
    Fields of seat
    • id uuid
    • name string
    • busy boolean
    • lastSeenAt date-time or null
  • people array of object
    Fields of people
    • id uuid
    • name string
    • level "owner"
    • validFrom date-time or null
    • validUntil date-time or null
  • projects array of object
    Fields of projects
    • id uuid
    • name string
    • hosts array of "github" or "gitlab" or "jira"
    • repositories array of string
  • tools array of object
    Fields of tools
    • connector string
    • name string
    • title string
    • policy "allow" or "ask" or "deny"
  • skills array of object
    Fields of skills
    • id uuid
    • name string
    • version string
    • privateTo string optional
  • mcpServers array of object
    Fields of mcpServers
    • id uuid
    • name string
    • privateTo string optional
  • memoryDocuments integer
  • spend object
    Fields of spend
    • usdThisMonth number
    • limit number or null
    • reached boolean
    • resumed boolean

PATCH /api/agents/{id}

Changes the identity, instructions, model or budget.

Path

  • id uuid required

Body

  • name string

    1 to 100 characters

  • roleTitle string

    up to 200 characters

  • instructions string

    up to 100,000 characters

  • modelPref string or null

    up to 100 characters

  • engine "claude-code" or "codex"
  • budget object or null
    Fields of budget
    • maxMinutes integer
    • maxTurns integer
    • maxTokens integer
    • usdPerMonth number

      0 to 1,000,000

  • runsOn "laptop" or "server"
  • modelConnectionId uuid or null
  • serverShell boolean

Answer 200

  • id uuid
  • name string
  • roleTitle string
  • status "active" or "archived"
  • owner object
    Fields of owner
    • id uuid
    • name string
  • lastRun object or null
    Fields of lastRun
    • id uuid
    • taskId uuid or null
    • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
    • at date-time
    • task object or null
      Fields of task
      • title string
      • project string or null
  • createdAt date-time
  • instructions string
  • engine "claude-code" or "codex"
  • modelPref string or null
  • runsOn "laptop" or "server"
  • modelConnection object or null
    Fields of modelConnection
    • id uuid
    • name string
  • serverShell boolean
  • budget object or null
    Fields of budget
    • maxMinutes integer optional
    • maxTurns integer optional
    • maxTokens integer optional
    • usdPerMonth number optional

      0 to 1,000,000

  • runDefaults object
    Fields of runDefaults
    • maxMinutes integer
    • maxTurns integer
    • maxTokens integer
  • copiedFromAgentId uuid or null
  • template object or null
    Fields of template
    • id uuid
    • name string
    • version integer
  • seat object or null
    Fields of seat
    • id uuid
    • name string
    • busy boolean
    • lastSeenAt date-time or null
  • people array of object
    Fields of people
    • id uuid
    • name string
    • level "owner"
    • validFrom date-time or null
    • validUntil date-time or null
  • projects array of object
    Fields of projects
    • id uuid
    • name string
    • hosts array of "github" or "gitlab" or "jira"
    • repositories array of string
  • tools array of object
    Fields of tools
    • connector string
    • name string
    • title string
    • policy "allow" or "ask" or "deny"
  • skills array of object
    Fields of skills
    • id uuid
    • name string
    • version string
    • privateTo string optional
  • mcpServers array of object
    Fields of mcpServers
    • id uuid
    • name string
    • privateTo string optional
  • memoryDocuments integer
  • spend object
    Fields of spend
    • usdThisMonth number
    • limit number or null
    • reached boolean
    • resumed boolean

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

  • id uuid required

Answer 200

  • tasks integer
  • handed integer
  • accepted integer
  • firstTime integer
  • changeRequests object
    Fields of changeRequests
    • merged integer
    • closed integer
    • open integer
  • returns object
    Fields of returns
    • total integer
    • tasks integer
    • person integer
    • ci integer
    • review integer
  • usd object
    Fields of usd
    • median string or null
    • total string or null
  • seconds object
    Fields of seconds
    • work integer or null
    • toReview integer or null
  • runs object
    Fields of runs
    • ended integer
    • failed integer
    • limited integer
  • since date-time
  • mostReturned array of object
    Fields of mostReturned
    • id uuid
    • title string
    • returns integer
    • usd string or null

POST /api/agents/{id}/budget/resume

Lets the agent go on past its monthly limit until the month ends.

Path

  • id uuid required

Answer 200

  • id uuid
  • name string
  • roleTitle string
  • status "active" or "archived"
  • owner object
    Fields of owner
    • id uuid
    • name string
  • lastRun object or null
    Fields of lastRun
    • id uuid
    • taskId uuid or null
    • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
    • at date-time
    • task object or null
      Fields of task
      • title string
      • project string or null
  • createdAt date-time
  • instructions string
  • engine "claude-code" or "codex"
  • modelPref string or null
  • runsOn "laptop" or "server"
  • modelConnection object or null
    Fields of modelConnection
    • id uuid
    • name string
  • serverShell boolean
  • budget object or null
    Fields of budget
    • maxMinutes integer optional
    • maxTurns integer optional
    • maxTokens integer optional
    • usdPerMonth number optional

      0 to 1,000,000

  • runDefaults object
    Fields of runDefaults
    • maxMinutes integer
    • maxTurns integer
    • maxTokens integer
  • copiedFromAgentId uuid or null
  • template object or null
    Fields of template
    • id uuid
    • name string
    • version integer
  • seat object or null
    Fields of seat
    • id uuid
    • name string
    • busy boolean
    • lastSeenAt date-time or null
  • people array of object
    Fields of people
    • id uuid
    • name string
    • level "owner"
    • validFrom date-time or null
    • validUntil date-time or null
  • projects array of object
    Fields of projects
    • id uuid
    • name string
    • hosts array of "github" or "gitlab" or "jira"
    • repositories array of string
  • tools array of object
    Fields of tools
    • connector string
    • name string
    • title string
    • policy "allow" or "ask" or "deny"
  • skills array of object
    Fields of skills
    • id uuid
    • name string
    • version string
    • privateTo string optional
  • mcpServers array of object
    Fields of mcpServers
    • id uuid
    • name string
    • privateTo string optional
  • memoryDocuments integer
  • spend object
    Fields of spend
    • usdThisMonth number
    • limit number or null
    • reached boolean
    • resumed boolean

POST /api/agents/{id}/duplicate

Copies the configuration into a new agent of the person; grants stay behind.

Path

  • id uuid required

Answer 201

  • id uuid
  • name string
  • roleTitle string
  • status "active" or "archived"
  • owner object
    Fields of owner
    • id uuid
    • name string
  • lastRun object or null
    Fields of lastRun
    • id uuid
    • taskId uuid or null
    • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
    • at date-time
    • task object or null
      Fields of task
      • title string
      • project string or null
  • createdAt date-time
  • instructions string
  • engine "claude-code" or "codex"
  • modelPref string or null
  • runsOn "laptop" or "server"
  • modelConnection object or null
    Fields of modelConnection
    • id uuid
    • name string
  • serverShell boolean
  • budget object or null
    Fields of budget
    • maxMinutes integer optional
    • maxTurns integer optional
    • maxTokens integer optional
    • usdPerMonth number optional

      0 to 1,000,000

  • runDefaults object
    Fields of runDefaults
    • maxMinutes integer
    • maxTurns integer
    • maxTokens integer
  • copiedFromAgentId uuid or null
  • template object or null
    Fields of template
    • id uuid
    • name string
    • version integer
  • seat object or null
    Fields of seat
    • id uuid
    • name string
    • busy boolean
    • lastSeenAt date-time or null
  • people array of object
    Fields of people
    • id uuid
    • name string
    • level "owner"
    • validFrom date-time or null
    • validUntil date-time or null
  • projects array of object
    Fields of projects
    • id uuid
    • name string
    • hosts array of "github" or "gitlab" or "jira"
    • repositories array of string
  • tools array of object
    Fields of tools
    • connector string
    • name string
    • title string
    • policy "allow" or "ask" or "deny"
  • skills array of object
    Fields of skills
    • id uuid
    • name string
    • version string
    • privateTo string optional
  • mcpServers array of object
    Fields of mcpServers
    • id uuid
    • name string
    • privateTo string optional
  • memoryDocuments integer
  • spend object
    Fields of spend
    • usdThisMonth number
    • limit number or null
    • reached boolean
    • resumed boolean

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

  • id uuid required

Body

  • to uuid required
  • until date-time

Answer 200

  • transferred array of object
    Fields of transferred
    • id uuid
    • name string
  • to object
    Fields of to
    • id uuid
    • name string
  • until date-time or null

GET /api/agents/{id}/export

The configuration as a JSON file, without ids, grants or secrets.

Path

  • id uuid required

Answer 200

  • format "agentome/agent@2"
  • agent object
    Fields of agent
    • name string

      1 to 100 characters

    • roleTitle string

      up to 200 characters

    • instructions string

      up to 100,000 characters

    • engine "claude-code" or "codex"
    • modelPref string or null

      up to 100 characters

    • budget object or null
      Fields of budget
      • maxMinutes integer optional
      • maxTurns integer optional
      • maxTokens integer optional
      • usdPerMonth number optional

        0 to 1,000,000

    • template object or null
      Fields of template
      • name string
      • version integer
    • skills array of object

      up to 50 items

      Fields of skills
      • content string

        1 to 100,000 characters

    • tools array of object

      up to 500 items

      Fields of tools
      • name string

        up to 200 characters

      • policy "allow" or "ask" or "deny"
    • mcpServers array of object

      up to 50 items

      Fields of mcpServers
      • name string

        up to 100 characters

  • source object optional
    Fields of source
    • name string

      up to 200 characters

    • url uri

      up to 500 characters

    • license string

      up 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

  • agent object
    Fields of agent
    • id uuid
    • name string
  • skills array of object
    Fields of skills
    • name string
    • version integer
    • added boolean
  • missingServers array of string

POST /api/agents/{id}/archive

Archives the agent: its queued runs are cancelled and it takes no more.

Path

  • id uuid required

Answer 200

  • id uuid
  • name string
  • roleTitle string
  • status "active" or "archived"
  • owner object
    Fields of owner
    • id uuid
    • name string
  • lastRun object or null
    Fields of lastRun
    • id uuid
    • taskId uuid or null
    • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
    • at date-time
    • task object or null
      Fields of task
      • title string
      • project string or null
  • createdAt date-time
  • instructions string
  • engine "claude-code" or "codex"
  • modelPref string or null
  • runsOn "laptop" or "server"
  • modelConnection object or null
    Fields of modelConnection
    • id uuid
    • name string
  • serverShell boolean
  • budget object or null
    Fields of budget
    • maxMinutes integer optional
    • maxTurns integer optional
    • maxTokens integer optional
    • usdPerMonth number optional

      0 to 1,000,000

  • runDefaults object
    Fields of runDefaults
    • maxMinutes integer
    • maxTurns integer
    • maxTokens integer
  • copiedFromAgentId uuid or null
  • template object or null
    Fields of template
    • id uuid
    • name string
    • version integer
  • seat object or null
    Fields of seat
    • id uuid
    • name string
    • busy boolean
    • lastSeenAt date-time or null
  • people array of object
    Fields of people
    • id uuid
    • name string
    • level "owner"
    • validFrom date-time or null
    • validUntil date-time or null
  • projects array of object
    Fields of projects
    • id uuid
    • name string
    • hosts array of "github" or "gitlab" or "jira"
    • repositories array of string
  • tools array of object
    Fields of tools
    • connector string
    • name string
    • title string
    • policy "allow" or "ask" or "deny"
  • skills array of object
    Fields of skills
    • id uuid
    • name string
    • version string
    • privateTo string optional
  • mcpServers array of object
    Fields of mcpServers
    • id uuid
    • name string
    • privateTo string optional
  • memoryDocuments integer
  • spend object
    Fields of spend
    • usdThisMonth number
    • limit number or null
    • reached boolean
    • resumed boolean

POST /api/agents/{id}/unarchive

Brings an archived agent back.

Path

  • id uuid required

Answer 200

  • id uuid
  • name string
  • roleTitle string
  • status "active" or "archived"
  • owner object
    Fields of owner
    • id uuid
    • name string
  • lastRun object or null
    Fields of lastRun
    • id uuid
    • taskId uuid or null
    • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
    • at date-time
    • task object or null
      Fields of task
      • title string
      • project string or null
  • createdAt date-time
  • instructions string
  • engine "claude-code" or "codex"
  • modelPref string or null
  • runsOn "laptop" or "server"
  • modelConnection object or null
    Fields of modelConnection
    • id uuid
    • name string
  • serverShell boolean
  • budget object or null
    Fields of budget
    • maxMinutes integer optional
    • maxTurns integer optional
    • maxTokens integer optional
    • usdPerMonth number optional

      0 to 1,000,000

  • runDefaults object
    Fields of runDefaults
    • maxMinutes integer
    • maxTurns integer
    • maxTokens integer
  • copiedFromAgentId uuid or null
  • template object or null
    Fields of template
    • id uuid
    • name string
    • version integer
  • seat object or null
    Fields of seat
    • id uuid
    • name string
    • busy boolean
    • lastSeenAt date-time or null
  • people array of object
    Fields of people
    • id uuid
    • name string
    • level "owner"
    • validFrom date-time or null
    • validUntil date-time or null
  • projects array of object
    Fields of projects
    • id uuid
    • name string
    • hosts array of "github" or "gitlab" or "jira"
    • repositories array of string
  • tools array of object
    Fields of tools
    • connector string
    • name string
    • title string
    • policy "allow" or "ask" or "deny"
  • skills array of object
    Fields of skills
    • id uuid
    • name string
    • version string
    • privateTo string optional
  • mcpServers array of object
    Fields of mcpServers
    • id uuid
    • name string
    • privateTo string optional
  • memoryDocuments integer
  • spend object
    Fields of spend
    • usdThisMonth number
    • limit number or null
    • reached boolean
    • resumed boolean

PUT /api/agents/{id}/tools/{name}

Sets the policy of one gateway tool: allow, ask the owner, or deny.

Path

  • id uuid required
  • name string required

    up to 200 characters

Body

  • policy "allow" or "ask" or "deny" required

Answer 200

  • id uuid
  • name string
  • roleTitle string
  • status "active" or "archived"
  • owner object
    Fields of owner
    • id uuid
    • name string
  • lastRun object or null
    Fields of lastRun
    • id uuid
    • taskId uuid or null
    • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
    • at date-time
    • task object or null
      Fields of task
      • title string
      • project string or null
  • createdAt date-time
  • instructions string
  • engine "claude-code" or "codex"
  • modelPref string or null
  • runsOn "laptop" or "server"
  • modelConnection object or null
    Fields of modelConnection
    • id uuid
    • name string
  • serverShell boolean
  • budget object or null
    Fields of budget
    • maxMinutes integer optional
    • maxTurns integer optional
    • maxTokens integer optional
    • usdPerMonth number optional

      0 to 1,000,000

  • runDefaults object
    Fields of runDefaults
    • maxMinutes integer
    • maxTurns integer
    • maxTokens integer
  • copiedFromAgentId uuid or null
  • template object or null
    Fields of template
    • id uuid
    • name string
    • version integer
  • seat object or null
    Fields of seat
    • id uuid
    • name string
    • busy boolean
    • lastSeenAt date-time or null
  • people array of object
    Fields of people
    • id uuid
    • name string
    • level "owner"
    • validFrom date-time or null
    • validUntil date-time or null
  • projects array of object
    Fields of projects
    • id uuid
    • name string
    • hosts array of "github" or "gitlab" or "jira"
    • repositories array of string
  • tools array of object
    Fields of tools
    • connector string
    • name string
    • title string
    • policy "allow" or "ask" or "deny"
  • skills array of object
    Fields of skills
    • id uuid
    • name string
    • version string
    • privateTo string optional
  • mcpServers array of object
    Fields of mcpServers
    • id uuid
    • name string
    • privateTo string optional
  • memoryDocuments integer
  • spend object
    Fields of spend
    • usdThisMonth number
    • limit number or null
    • reached boolean
    • resumed boolean

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

  • id uuid required

Body

  • policy "allow" or "ask" required

Answer 200

  • id uuid
  • name string
  • roleTitle string
  • status "active" or "archived"
  • owner object
    Fields of owner
    • id uuid
    • name string
  • lastRun object or null
    Fields of lastRun
    • id uuid
    • taskId uuid or null
    • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
    • at date-time
    • task object or null
      Fields of task
      • title string
      • project string or null
  • createdAt date-time
  • instructions string
  • engine "claude-code" or "codex"
  • modelPref string or null
  • runsOn "laptop" or "server"
  • modelConnection object or null
    Fields of modelConnection
    • id uuid
    • name string
  • serverShell boolean
  • budget object or null
    Fields of budget
    • maxMinutes integer optional
    • maxTurns integer optional
    • maxTokens integer optional
    • usdPerMonth number optional

      0 to 1,000,000

  • runDefaults object
    Fields of runDefaults
    • maxMinutes integer
    • maxTurns integer
    • maxTokens integer
  • copiedFromAgentId uuid or null
  • template object or null
    Fields of template
    • id uuid
    • name string
    • version integer
  • seat object or null
    Fields of seat
    • id uuid
    • name string
    • busy boolean
    • lastSeenAt date-time or null
  • people array of object
    Fields of people
    • id uuid
    • name string
    • level "owner"
    • validFrom date-time or null
    • validUntil date-time or null
  • projects array of object
    Fields of projects
    • id uuid
    • name string
    • hosts array of "github" or "gitlab" or "jira"
    • repositories array of string
  • tools array of object
    Fields of tools
    • connector string
    • name string
    • title string
    • policy "allow" or "ask" or "deny"
  • skills array of object
    Fields of skills
    • id uuid
    • name string
    • version string
    • privateTo string optional
  • mcpServers array of object
    Fields of mcpServers
    • id uuid
    • name string
    • privateTo string optional
  • memoryDocuments integer
  • spend object
    Fields of spend
    • usdThisMonth number
    • limit number or null
    • reached boolean
    • resumed boolean

GET /api/agents/{id}/workspace-preview

The CLAUDE.md and settings a run of the agent gets, as it is saved.

Path

  • id uuid required

Answer 200

  • claudeMd string
  • projectMd string optional
  • settings object
    Fields of settings
    • permissionMode "acceptEdits"
    • allowedTools array of string
    • sandbox object
      Fields of sandbox
      • enabled boolean
      • failIfUnavailable boolean
      • autoAllowBashIfSandboxed boolean
      • allowUnsandboxedCommands false
      • network object
        Fields of network
        • allowedDomains array of string
        • strictAllowlist true
        • allowLocalBinding true optional

GET /api/agents/{id}/memory

The agent's memory documents as they are now.

Path

  • id uuid required

Answer 200

  • documents array of object
    Fields of documents
    • path string
    • version integer
    • content string
    • updatedAt date-time
    • updatedBy object or object

PUT /api/agents/{id}/memory

Writes a new version of a memory document.

Path

  • id uuid required

Body

  • path string required
  • content string required

    1 to 100,000 characters

  • baseVersion integer

Answer 200

  • path string
  • version integer
  • content string
  • updatedAt date-time
  • updatedBy object or object

DELETE /api/agents/{id}/memory

Deletes a memory document; its history stays.

Path

  • id uuid required

Query

  • path string required
  • baseVersion integer

Answer

200.

GET /api/agents/{id}/memory/versions

Every version of one memory document, newest first.

Path

  • id uuid required

Query

  • path string required

Answer 200

  • path string
  • versions array of object
    Fields of versions
    • path string
    • version integer
    • content string
    • updatedAt date-time
    • updatedBy object or object

POST /api/agents/{id}/memory/revert

Brings back an earlier version of a memory document, as a new version.

Path

  • id uuid required

Body

  • path string required
  • version integer required

Answer 200

  • path string
  • version integer
  • content string
  • updatedAt date-time
  • updatedBy object or object

PUT /api/agents/{id}/skills

Sets the agent's skills, each at the version given.

Path

  • id uuid required

Body

  • skills array of uuid required

    up to 50 items

Answer 200

  • skills array of object
    Fields of skills
    • id uuid
    • name string
    • description string
    • version integer
    • owner object or null
      Fields of owner
      • id uuid
      • name string
    • visibility "org" or "private"
    • createdAt date-time

PUT /api/agents/{id}/mcp

Sets the agent's MCP servers; their tools ask the owner until a policy says otherwise.

Path

  • id uuid required

Body

  • servers array of uuid required

    up to 20 items

Answer 200

  • servers array of object
    Fields of servers
    • id uuid
    • name string
    • description string
    • url string
    • hasAuthorization boolean
    • auth "header" or "oauth"
    • signedIn boolean
    • tools array of object
      Fields of tools
      • name string
      • title string
      • description string
    • checkedAt date-time
    • owner object or null
      Fields of owner
      • id uuid
      • name string
    • visibility "org" or "private"

GET /api/agents/{id}/schedules

The agent's recurring tasks.

Path

  • id uuid required

Answer 200

  • schedules array of object
    Fields of schedules
    • id uuid
    • title string
    • body string
    • projectId uuid or null
    • repository string or null
    • days array of integer
    • time string
    • timeZone string
    • enabled boolean
    • when string
    • lastRunAt date-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

  • id uuid required

Body

  • title string required

    1 to 200 characters

  • body string

    up to 100,000 characters

  • projectId uuid required
  • repository string or null

    up to 2,000 characters; default null

  • days array of integer required

    up to 7 items

  • time string required
  • timeZone string required
  • enabled boolean

    default true

Answer 201

  • id uuid
  • title string
  • body string
  • projectId uuid or null
  • repository string or null
  • days array of integer
  • time string
  • timeZone string
  • enabled boolean
  • when string
  • lastRunAt date-time or null

PATCH /api/agents/{id}/schedules/{scheduleId}

Changes a recurring task, or turns it off and on.

Path

  • id uuid required
  • scheduleId uuid required

Body

  • title string

    1 to 200 characters

  • body string

    up to 100,000 characters

  • projectId uuid
  • repository string or null

    up to 2,000 characters; default null

  • days array of integer

    up to 7 items

  • time string
  • timeZone string
  • enabled boolean

    default true

Answer 200

  • id uuid
  • title string
  • body string
  • projectId uuid or null
  • repository string or null
  • days array of integer
  • time string
  • timeZone string
  • enabled boolean
  • when string
  • lastRunAt date-time or null

DELETE /api/agents/{id}/schedules/{scheduleId}

Removes a recurring task.

Path

  • id uuid required
  • scheduleId uuid 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

  • agent uuid
  • project uuid
  • status "open" or "review" or "done"
  • limit integer

    1 to 100; default 50

  • before string
  • all string

Answer 200

  • tasks array of object
    Fields of tasks
    • id uuid
    • title string
    • agent object
      Fields of agent
      • id uuid
      • name string
    • status "open" or "review" or "done"
    • source "manual" or "jira" or "cron" or "webhook" or "chat" or "agent"
    • repository string or null
    • repositoryFromProject boolean
    • createdBy object
      Fields of createdBy
      • id uuid
      • name string
    • createdAt date-time
    • latestRun object or null
      Fields of latestRun
      • id uuid
      • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
      • at date-time
    • project object or null
      Fields of project
      • id uuid
      • name string
    • changeRequest object or null
      Fields of changeRequest
      • state "open" or "draft" or "merged" or "closed" or null

        default null

      • pipeline "none" or "running" or "success" or "failed" or null

        default null

      • url string
  • nextBefore string 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

  • projectId uuid required
  • agentId uuid
  • title string required

    1 to 200 characters

  • body string

    up to 100,000 characters

  • repository string or null

    up to 2,000 characters

  • run boolean

Answer 201

  • task object
    Fields of task
    • id uuid
    • title string
    • agent object
      Fields of agent
      • id uuid
      • name string
      • status "active" or "archived"
    • status "open" or "review" or "done"
    • source "manual" or "jira" or "cron" or "webhook" or "chat" or "agent"
    • repository string or null
    • repositoryFromProject boolean
    • createdBy object
      Fields of createdBy
      • id uuid
      • name string
    • createdAt date-time
    • latestRun object or null
      Fields of latestRun
      • id uuid
      • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
      • at date-time
    • project object or null
      Fields of project
      • id uuid
      • name string
    • changeRequest object or null
      Fields of changeRequest
      • state "open" or "draft" or "merged" or "closed" or null

        default null

      • pipeline "none" or "running" or "success" or "failed" or null

        default null

      • url string
    • body string
    • externalError string or null
    • connection object or null
      Fields of connection
      • id uuid
      • kind "github" or "gitlab" or "jira"
      • project object
        Fields of project
        • id uuid
        • name string
    • parent object or null
      Fields of parent
      • id uuid
      • title string
      • agent string
    • subtasks array of object
      Fields of subtasks
      • id uuid
      • title string
      • agent string
      • status "open" or "review" or "done"
      • runStatus "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled" or null
    • runs array of object
      Fields of runs
      • id uuid
      • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
      • startedAt date-time or null
      • endedAt date-time or null
      • errorCode string or null
      • summary string or null
      • seat object or null
        Fields of seat
        • name string
      • createdAt date-time
      • usd string or null
    • changeRequests array of object
      Fields of changeRequests
      • state "open" or "draft" or "merged" or "closed" or null

        default null

      • pipeline "none" or "running" or "success" or "failed" or null

        default null

      • review "approved" or "changes_requested" or "commented" or null

        default null

      • url string
      • runId string
      • createdAt date-time
    • comments array of object
      Fields of comments
      • id uuid
      • body string
      • runId uuid or null
      • createdAt date-time
      • author object
        Fields of author
        • kind "person" or "agent"
        • id uuid
        • name string
    • questions array of object
      Fields of questions
      • id uuid
      • runId uuid
      • question string
      • answer string or null
      • state "waiting" or "answered" or "skipped" or "unanswered"
      • askedAt date-time
      • answeredAt date-time or null
      • answeredBy string or null
  • run object or null
    Fields of run
    • id uuid
    • status "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

  • folders array of string

GET /api/tasks/{id}

A task with its description and its runs, newest first.

Path

  • id uuid required

Answer 200

  • id uuid
  • title string
  • agent object
    Fields of agent
    • id uuid
    • name string
    • status "active" or "archived"
  • status "open" or "review" or "done"
  • source "manual" or "jira" or "cron" or "webhook" or "chat" or "agent"
  • repository string or null
  • repositoryFromProject boolean
  • createdBy object
    Fields of createdBy
    • id uuid
    • name string
  • createdAt date-time
  • latestRun object or null
    Fields of latestRun
    • id uuid
    • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
    • at date-time
  • project object or null
    Fields of project
    • id uuid
    • name string
  • changeRequest object or null
    Fields of changeRequest
    • state "open" or "draft" or "merged" or "closed" or null

      default null

    • pipeline "none" or "running" or "success" or "failed" or null

      default null

    • url string
  • body string
  • externalError string or null
  • connection object or null
    Fields of connection
    • id uuid
    • kind "github" or "gitlab" or "jira"
    • project object
      Fields of project
      • id uuid
      • name string
  • parent object or null
    Fields of parent
    • id uuid
    • title string
    • agent string
  • subtasks array of object
    Fields of subtasks
    • id uuid
    • title string
    • agent string
    • status "open" or "review" or "done"
    • runStatus "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled" or null
  • runs array of object
    Fields of runs
    • id uuid
    • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
    • startedAt date-time or null
    • endedAt date-time or null
    • errorCode string or null
    • summary string or null
    • seat object or null
      Fields of seat
      • name string
    • createdAt date-time
    • usd string or null
  • changeRequests array of object
    Fields of changeRequests
    • state "open" or "draft" or "merged" or "closed" or null

      default null

    • pipeline "none" or "running" or "success" or "failed" or null

      default null

    • review "approved" or "changes_requested" or "commented" or null

      default null

    • url string
    • runId string
    • createdAt date-time
  • comments array of object
    Fields of comments
    • id uuid
    • body string
    • runId uuid or null
    • createdAt date-time
    • author object
      Fields of author
      • kind "person" or "agent"
      • id uuid
      • name string
  • questions array of object
    Fields of questions
    • id uuid
    • runId uuid
    • question string
    • answer string or null
    • state "waiting" or "answered" or "skipped" or "unanswered"
    • askedAt date-time
    • answeredAt date-time or null
    • answeredBy string or null

PATCH /api/tasks/{id}

Changes the title, description, repository or status (open, review or done).

Path

  • id uuid required

Body

  • title string

    1 to 200 characters

  • body string

    up to 100,000 characters

  • repository string or null

    up to 2,000 characters

  • status "open" or "review" or "done"

Answer 200

  • id uuid
  • title string
  • agent object
    Fields of agent
    • id uuid
    • name string
    • status "active" or "archived"
  • status "open" or "review" or "done"
  • source "manual" or "jira" or "cron" or "webhook" or "chat" or "agent"
  • repository string or null
  • repositoryFromProject boolean
  • createdBy object
    Fields of createdBy
    • id uuid
    • name string
  • createdAt date-time
  • latestRun object or null
    Fields of latestRun
    • id uuid
    • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
    • at date-time
  • project object or null
    Fields of project
    • id uuid
    • name string
  • changeRequest object or null
    Fields of changeRequest
    • state "open" or "draft" or "merged" or "closed" or null

      default null

    • pipeline "none" or "running" or "success" or "failed" or null

      default null

    • url string
  • body string
  • externalError string or null
  • connection object or null
    Fields of connection
    • id uuid
    • kind "github" or "gitlab" or "jira"
    • project object
      Fields of project
      • id uuid
      • name string
  • parent object or null
    Fields of parent
    • id uuid
    • title string
    • agent string
  • subtasks array of object
    Fields of subtasks
    • id uuid
    • title string
    • agent string
    • status "open" or "review" or "done"
    • runStatus "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled" or null
  • runs array of object
    Fields of runs
    • id uuid
    • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
    • startedAt date-time or null
    • endedAt date-time or null
    • errorCode string or null
    • summary string or null
    • seat object or null
      Fields of seat
      • name string
    • createdAt date-time
    • usd string or null
  • changeRequests array of object
    Fields of changeRequests
    • state "open" or "draft" or "merged" or "closed" or null

      default null

    • pipeline "none" or "running" or "success" or "failed" or null

      default null

    • review "approved" or "changes_requested" or "commented" or null

      default null

    • url string
    • runId string
    • createdAt date-time
  • comments array of object
    Fields of comments
    • id uuid
    • body string
    • runId uuid or null
    • createdAt date-time
    • author object
      Fields of author
      • kind "person" or "agent"
      • id uuid
      • name string
  • questions array of object
    Fields of questions
    • id uuid
    • runId uuid
    • question string
    • answer string or null
    • state "waiting" or "answered" or "skipped" or "unanswered"
    • askedAt date-time
    • answeredAt date-time or null
    • answeredBy string 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

  • id uuid required

Answer 200

  • branches array of object
    Fields of branches
    • name string
    • commits array of object
      Fields of commits
      • sha string
      • subject string
    • additions integer or null
    • deletions integer or null
    • files integer or null
    • url string or null
  • changeRequests array of object
    Fields of changeRequests
    • url string
    • number integer or null
    • title string or null
    • state "open" or "draft" or "merged" or "closed" or null

      default null

    • pipeline "none" or "running" or "success" or "failed" or null

      default null

  • problem string or null

POST /api/tasks/{id}/run

Queues another run of the task, for a seat of the agent's owner.

Path

  • id uuid required

Answer 201

  • id uuid
  • status "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

  • id uuid required

Body

  • body string required

    1 to 20,000 characters

  • run boolean

    default false

Answer 201

  • id uuid
  • run object or null
    Fields of run
    • id uuid
    • status "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

  • id uuid required

Query

  • all "true" or "false"

    An admin reads every run; default "false"

  • after integer

    default -1

Answer 200

  • events array of any
  • nextAfter integer or null

POST /api/runs/{id}/cancel

Cancels a queued run, or asks the seat to stop a running one.

Path

  • id uuid required

Answer 200

  • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
  • cancelRequested boolean

GET /api/runs

Runs the signed-in person may read, newest first.

Query

  • all "true" or "false"

    An admin reads every run; default "false"

  • agent uuid
  • task uuid
  • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled" or "live"
  • limit integer

    1 to 100; default 50

  • before date-time

Answer 200

  • runs array of object
    Fields of runs
    • id uuid
    • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
    • agent object
      Fields of agent
      • id uuid
      • name string
    • task object or null
      Fields of task
      • id uuid
      • title string
      • projectId uuid or null
    • seat object or null
      Fields of seat
      • id uuid
      • name string
      • owner object
        Fields of owner
        • id uuid
        • name string
    • startedBy object
      Fields of startedBy
      • kind "user" or "cron" or "webhook" or "agent"
      • user object or null
        Fields of user
        • id uuid
        • name string
    • startedAt date-time or null
    • endedAt date-time or null
    • errorCode string or null
    • createdAt date-time
    • cost object
      Fields of cost
      • usd string or null
      • tokens integer
  • nextBefore date-time or null

GET /api/runs/{id}

A run with its artifacts and cost.

Path

  • id uuid required

Query

  • all "true" or "false"

    An admin reads every run; default "false"

Answer 200

  • id uuid
  • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
  • agent object
    Fields of agent
    • id uuid
    • name string
  • task object or null
    Fields of task
    • id uuid
    • title string
    • projectId uuid or null
  • seat object or null
    Fields of seat
    • id uuid
    • name string
    • owner object
      Fields of owner
      • id uuid
      • name string
  • startedBy object
    Fields of startedBy
    • kind "user" or "cron" or "webhook" or "agent"
    • user object or null
      Fields of user
      • id uuid
      • name string
  • startedAt date-time or null
  • endedAt date-time or null
  • errorCode string or null
  • createdAt date-time
  • limits object or null
    Fields of limits
    • maxMinutes integer
    • maxTurns integer
    • maxTokens integer
  • cancelRequestedAt date-time or null
  • summary string or null
  • artifacts array of object
    Fields of artifacts
    • id uuid
    • kind "branch" or "change_request" or "file" or "report"
    • ref string
    • meta object
    • createdAt date-time
  • toolCalls array of object
    Fields of toolCalls
    • tool string
    • agentId uuid
    • decision "allowed" or "pending" or "approved" or "denied"
    • reason string or null
    • decidedBy object or null
      Fields of decidedBy
      • id string
      • name string
    • createdAt date-time
    • members array of uuid optional
  • team array of object
    Fields of team
    • key string
    • agentId uuid
    • name string
  • cost object
    Fields of cost
    • rows array of object
      Fields of rows
      • model string
      • tokensIn integer
      • tokensOut integer
      • tokensCacheRead integer
      • tokensCacheWrite integer
      • usd string or null
    • totalUsd string or null
    • unpriced boolean

GET /api/runs/{id}/stream

The transcript of a run as server-sent events, live until the run ends.

Path

  • id uuid required

Query

  • all "true" or "false"

    An admin reads every run; default "false"

  • after integer

    default -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

  • approvals array of object
    Fields of approvals
    • id uuid
    • tool string
    • input any
    • runId uuid
    • agent object
      Fields of agent
      • id uuid
      • name string
    • task object or null
      Fields of task
      • id uuid
      • title string
      • repository string or null
    • createdAt date-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

  • id uuid required

Body

  • always boolean

Answer 200

  • decision "allowed" or "pending" or "approved" or "denied"
  • reason string or null

POST /api/tool-calls/{id}/answer

Answers an agent's question (ask_owner); the agent reads the answer.

Path

  • id uuid required

Body

  • answer string required

    1 to 4,000 characters

Answer 200

  • decision "allowed" or "pending" or "approved" or "denied"
  • reason string or null

POST /api/tool-calls/{id}/deny

Refuses a waiting tool call; the agent reads the reason.

Path

  • id uuid required

Body

  • reason string

    up to 1,000 characters

Answer 200

  • decision "allowed" or "pending" or "approved" or "denied"
  • reason string or null

Projects

Projects with their repositories, agents, knowledge and the services their runs need.

GET /api/projects

Every project, newest first.

Answer 200

  • projects array of object
    Fields of projects
    • id uuid
    • name string
    • agentCount integer
    • connectionCount integer
    • createdBy uuid
    • createdAt date-time
    • team object or null
      Fields of team
      • id uuid
      • name string
    • week object
      Fields of week
      • runs integer
      • ended integer
      • done integer
      • medianSeconds integer or null
      • usd string or null
      • daily array of integer
    • lastRun object or null
      Fields of lastRun
      • id uuid
      • status "queued" or "running" or "waiting_approval" or "done" or "failed" or "cancelled"
      • at date-time
      • agent object
        Fields of agent
        • id uuid
        • name string
      • task object
        Fields of task
        • id uuid
        • title string

POST /api/projects

Creates a project.

Body

  • name string required

    1 to 100 characters

  • description string

    up to 100,000 characters

  • goals string

    up to 100,000 characters

Answer 201

  • id uuid
  • name string
  • agentCount integer
  • connectionCount integer
  • createdBy uuid
  • createdAt date-time
  • team object or null
    Fields of team
    • id uuid
    • name string
    • lead object
      Fields of lead
      • id uuid
      • name string
  • intake "manual" or "auto"
  • budget object
    Fields of budget
    • usdPerMonth number or null
    • usdThisMonth number
  • triggers object
    Fields of triggers
    • onPipelineFailed boolean
    • onReview boolean
    • reviewer object or null
      Fields of reviewer
      • id uuid
      • name string
  • description string
  • goals string
  • repositories array of string
  • allowedHosts array of string
  • environment object or null
    Fields of environment
    • repository string
    • devcontainer string or null
    • services array of object
      Fields of services
      • name string
      • image string

        up to 255 characters

      • environment object
      • command array of string optional

        up to 64 items

      • volumes array of object

        up to 8 items

        Fields of volumes
        • name string
        • target string

          up to 255 characters

    • problems array of string
    • readAt date-time
    • hash string
    • approved boolean
  • agents array of object
    Fields of agents
    • id uuid
    • name string
    • roleTitle string
    • status "active" or "archived"
  • connections array of object
    Fields of connections
    • id uuid
    • kind "github" or "gitlab" or "jira"
    • host string
    • namespace string
    • accountLogin string or null
    • agentName string or null
  • week object
    Fields of week
    • runs integer
    • ended integer
    • done integer
    • medianSeconds integer or null
    • usd string or null
    • daily array of integer

GET /api/projects/{id}

A project with its agents and connections.

Path

  • id uuid required

Answer 200

  • id uuid
  • name string
  • agentCount integer
  • connectionCount integer
  • createdBy uuid
  • createdAt date-time
  • team object or null
    Fields of team
    • id uuid
    • name string
    • lead object
      Fields of lead
      • id uuid
      • name string
  • intake "manual" or "auto"
  • budget object
    Fields of budget
    • usdPerMonth number or null
    • usdThisMonth number
  • triggers object
    Fields of triggers
    • onPipelineFailed boolean
    • onReview boolean
    • reviewer object or null
      Fields of reviewer
      • id uuid
      • name string
  • description string
  • goals string
  • repositories array of string
  • allowedHosts array of string
  • environment object or null
    Fields of environment
    • repository string
    • devcontainer string or null
    • services array of object
      Fields of services
      • name string
      • image string

        up to 255 characters

      • environment object
      • command array of string optional

        up to 64 items

      • volumes array of object

        up to 8 items

        Fields of volumes
        • name string
        • target string

          up to 255 characters

    • problems array of string
    • readAt date-time
    • hash string
    • approved boolean
  • agents array of object
    Fields of agents
    • id uuid
    • name string
    • roleTitle string
    • status "active" or "archived"
  • connections array of object
    Fields of connections
    • id uuid
    • kind "github" or "gitlab" or "jira"
    • host string
    • namespace string
    • accountLogin string or null
    • agentName string or null
  • week object
    Fields of week
    • runs integer
    • ended integer
    • done integer
    • medianSeconds integer or null
    • usd string or null
    • daily array 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

  • id uuid required

Body

  • name string

    1 to 100 characters

  • description string

    up to 100,000 characters

  • goals string

    up to 100,000 characters

  • repositories array of uri

    up to 20 items

  • allowedHosts array of string

    up to 100 items

  • teamId uuid or null
  • intake "manual" or "auto"
  • usdPerMonth number or null

    0 to 1,000,000

  • onPipelineFailed boolean
  • onReview boolean
  • reviewerAgentId uuid or null

Answer 200

  • id uuid
  • name string
  • agentCount integer
  • connectionCount integer
  • createdBy uuid
  • createdAt date-time
  • team object or null
    Fields of team
    • id uuid
    • name string
    • lead object
      Fields of lead
      • id uuid
      • name string
  • intake "manual" or "auto"
  • budget object
    Fields of budget
    • usdPerMonth number or null
    • usdThisMonth number
  • triggers object
    Fields of triggers
    • onPipelineFailed boolean
    • onReview boolean
    • reviewer object or null
      Fields of reviewer
      • id uuid
      • name string
  • description string
  • goals string
  • repositories array of string
  • allowedHosts array of string
  • environment object or null
    Fields of environment
    • repository string
    • devcontainer string or null
    • services array of object
      Fields of services
      • name string
      • image string

        up to 255 characters

      • environment object
      • command array of string optional

        up to 64 items

      • volumes array of object

        up to 8 items

        Fields of volumes
        • name string
        • target string

          up to 255 characters

    • problems array of string
    • readAt date-time
    • hash string
    • approved boolean
  • agents array of object
    Fields of agents
    • id uuid
    • name string
    • roleTitle string
    • status "active" or "archived"
  • connections array of object
    Fields of connections
    • id uuid
    • kind "github" or "gitlab" or "jira"
    • host string
    • namespace string
    • accountLogin string or null
    • agentName string or null
  • week object
    Fields of week
    • runs integer
    • ended integer
    • done integer
    • medianSeconds integer or null
    • usd string or null
    • daily array of integer

DELETE /api/projects/{id}

Deletes a project with its connections, knowledge and assignments; its tasks stay.

Path

  • id uuid 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

  • id uuid required

Answer 200

  • hosts array of object
    Fields of hosts
    • host string
    • port number
    • count number
    • lastAt date-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

  • id uuid required

Answer 200

  • id uuid
  • name string
  • agentCount integer
  • connectionCount integer
  • createdBy uuid
  • createdAt date-time
  • team object or null
    Fields of team
    • id uuid
    • name string
    • lead object
      Fields of lead
      • id uuid
      • name string
  • intake "manual" or "auto"
  • budget object
    Fields of budget
    • usdPerMonth number or null
    • usdThisMonth number
  • triggers object
    Fields of triggers
    • onPipelineFailed boolean
    • onReview boolean
    • reviewer object or null
      Fields of reviewer
      • id uuid
      • name string
  • description string
  • goals string
  • repositories array of string
  • allowedHosts array of string
  • environment object or null
    Fields of environment
    • repository string
    • devcontainer string or null
    • services array of object
      Fields of services
      • name string
      • image string

        up to 255 characters

      • environment object
      • command array of string optional

        up to 64 items

      • volumes array of object

        up to 8 items

        Fields of volumes
        • name string
        • target string

          up to 255 characters

    • problems array of string
    • readAt date-time
    • hash string
    • approved boolean
  • agents array of object
    Fields of agents
    • id uuid
    • name string
    • roleTitle string
    • status "active" or "archived"
  • connections array of object
    Fields of connections
    • id uuid
    • kind "github" or "gitlab" or "jira"
    • host string
    • namespace string
    • accountLogin string or null
    • agentName string or null
  • week object
    Fields of week
    • runs integer
    • ended integer
    • done integer
    • medianSeconds integer or null
    • usd string or null
    • daily array 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

  • id uuid required

Body

  • hash string required

Answer 200

  • id uuid
  • name string
  • agentCount integer
  • connectionCount integer
  • createdBy uuid
  • createdAt date-time
  • team object or null
    Fields of team
    • id uuid
    • name string
    • lead object
      Fields of lead
      • id uuid
      • name string
  • intake "manual" or "auto"
  • budget object
    Fields of budget
    • usdPerMonth number or null
    • usdThisMonth number
  • triggers object
    Fields of triggers
    • onPipelineFailed boolean
    • onReview boolean
    • reviewer object or null
      Fields of reviewer
      • id uuid
      • name string
  • description string
  • goals string
  • repositories array of string
  • allowedHosts array of string
  • environment object or null
    Fields of environment
    • repository string
    • devcontainer string or null
    • services array of object
      Fields of services
      • name string
      • image string

        up to 255 characters

      • environment object
      • command array of string optional

        up to 64 items

      • volumes array of object

        up to 8 items

        Fields of volumes
        • name string
        • target string

          up to 255 characters

    • problems array of string
    • readAt date-time
    • hash string
    • approved boolean
  • agents array of object
    Fields of agents
    • id uuid
    • name string
    • roleTitle string
    • status "active" or "archived"
  • connections array of object
    Fields of connections
    • id uuid
    • kind "github" or "gitlab" or "jira"
    • host string
    • namespace string
    • accountLogin string or null
    • agentName string or null
  • week object
    Fields of week
    • runs integer
    • ended integer
    • done integer
    • medianSeconds integer or null
    • usd string or null
    • daily array of integer

PUT /api/projects/{id}/agents/{agentId}

Assigns an agent to a project.

Path

  • id uuid required
  • agentId uuid required

Answer

200.

DELETE /api/projects/{id}/agents/{agentId}

Takes an agent off a project.

Path

  • id uuid required
  • agentId uuid required

Answer

200.

GET /api/projects/{id}/knowledge

A project's knowledge sources, with when each last synced.

Path

  • id uuid required

Answer 200

  • sources array of object
    Fields of sources
    • id uuid
    • repository string
    • paths array of string
    • lastSyncAt date-time or null
    • lastSyncError string or null
    • documents integer

POST /api/projects/{id}/knowledge

Adds markdown of a connected repository to the project, and syncs it.

Path

  • id uuid required

Body

  • repository uri required

    up to 500 characters

  • paths array of string required

    up to 20 items

Answer 201

  • id uuid
  • repository string
  • paths array of string
  • lastSyncAt date-time or null
  • lastSyncError string or null
  • documents integer

POST /api/knowledge/{id}/sync

Syncs a source now; a failure is in the answer, as lastSyncError.

Path

  • id uuid required

Answer 200

  • id uuid
  • repository string
  • paths array of string
  • lastSyncAt date-time or null
  • lastSyncError string or null
  • documents integer

DELETE /api/knowledge/{id}

Removes a source and its documents.

Path

  • id uuid 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

  • teams array of object
    Fields of teams
    • id uuid
    • name string
    • mode "auto" or "manual"
    • lead object
      Fields of lead
      • id uuid
      • name string
      • roleTitle string
      • status "active" or "archived"
    • members array of object
      Fields of members
      • id uuid
      • name string
      • roleTitle string
      • status "active" or "archived"
    • steps array of object

      up to 10 items

      Fields of steps
      • agents array of uuid

        up to 10 items

      • note string

        up 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

  • name string required

    1 to 100 characters

  • leadId uuid required
  • mode "auto" or "manual"

    default "auto"

  • members array of uuid

    up to 10 items; default []

  • steps array of object

    up to 10 items; default []

    Fields of steps
    • agents array of uuid required

      up to 10 items

    • note string required

      up to 1,000 characters

Answer 201

  • id uuid
  • name string
  • mode "auto" or "manual"
  • lead object
    Fields of lead
    • id uuid
    • name string
    • roleTitle string
    • status "active" or "archived"
  • members array of object
    Fields of members
    • id uuid
    • name string
    • roleTitle string
    • status "active" or "archived"
  • steps array of object

    up to 10 items

    Fields of steps
    • agents array of uuid

      up to 10 items

    • note string

      up to 1,000 characters

GET /api/teams/{id}

One team.

Path

  • id uuid required

Answer 200

  • id uuid
  • name string
  • mode "auto" or "manual"
  • lead object
    Fields of lead
    • id uuid
    • name string
    • roleTitle string
    • status "active" or "archived"
  • members array of object
    Fields of members
    • id uuid
    • name string
    • roleTitle string
    • status "active" or "archived"
  • steps array of object

    up to 10 items

    Fields of steps
    • agents array of uuid

      up to 10 items

    • note string

      up 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

  • id uuid required

Body

  • name string

    1 to 100 characters

  • leadId uuid
  • mode "auto" or "manual"
  • members array of uuid

    up to 10 items

  • steps array of object

    up to 10 items

    Fields of steps
    • agents array of uuid required

      up to 10 items

    • note string required

      up to 1,000 characters

Answer 200

  • id uuid
  • name string
  • mode "auto" or "manual"
  • lead object
    Fields of lead
    • id uuid
    • name string
    • roleTitle string
    • status "active" or "archived"
  • members array of object
    Fields of members
    • id uuid
    • name string
    • roleTitle string
    • status "active" or "archived"
  • steps array of object

    up to 10 items

    Fields of steps
    • agents array of uuid

      up to 10 items

    • note string

      up to 1,000 characters

DELETE /api/teams/{id}

Removes a team; its agents stay.

Path

  • id uuid 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

  • id uuid required

Answer 201

  • id uuid
  • name string
  • mode "auto" or "manual"
  • lead object
    Fields of lead
    • id uuid
    • name string
    • roleTitle string
    • status "active" or "archived"
  • members array of object
    Fields of members
    • id uuid
    • name string
    • roleTitle string
    • status "active" or "archived"
  • steps array of object

    up to 10 items

    Fields of steps
    • agents array of uuid

      up to 10 items

    • note string

      up 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

  • skills array of object
    Fields of skills
    • id uuid
    • name string
    • description string
    • version integer
    • owner object or null
      Fields of owner
      • id uuid
      • name string
    • visibility "org" or "private"
    • createdAt date-time

POST /api/library/skills

Adds a skill for the person, from its SKILL.md.

Body

  • content string required

    1 to 100,000 characters

Answer 201

  • id uuid
  • name string
  • description string
  • version integer
  • owner object or null
    Fields of owner
    • id uuid
    • name string
  • visibility "org" or "private"
  • createdAt date-time
  • content string

GET /api/library/skills/{id}

One version of a skill, with its SKILL.md.

Path

  • id uuid required

Answer 200

  • id uuid
  • name string
  • description string
  • version integer
  • owner object or null
    Fields of owner
    • id uuid
    • name string
  • visibility "org" or "private"
  • createdAt date-time
  • content string

DELETE /api/library/skills/{id}

Deletes a skill with every version: its author, or an admin once it is shared.

Path

  • id uuid required

Answer 204

null

GET /api/library/skills/{id}/agents

The person's agents that have the skill, at any version of it.

Path

  • id uuid required

Answer 200

  • agents array of object
    Fields of agents
    • id uuid
    • name string

POST /api/library/skills/{id}/versions

Adds a version to the person's own skill; agents keep theirs until moved on.

Path

  • id uuid required

Body

  • content string required

    1 to 100,000 characters

Answer 201

  • id uuid
  • name string
  • description string
  • version integer
  • owner object or null
    Fields of owner
    • id uuid
    • name string
  • visibility "org" or "private"
  • createdAt date-time
  • content string

POST /api/library/skills/{id}/share

Shares a skill with everyone: every version of it, now and to come.

Path

  • id uuid required

Answer 200

  • id uuid
  • name string
  • description string
  • version integer
  • owner object or null
    Fields of owner
    • id uuid
    • name string
  • visibility "org" or "private"
  • createdAt date-time
  • content string

GET /api/library/mcp

The MCP servers the person may give their agents.

Answer 200

  • servers array of object
    Fields of servers
    • id uuid
    • name string
    • description string
    • url string
    • hasAuthorization boolean
    • auth "header" or "oauth"
    • signedIn boolean
    • tools array of object
      Fields of tools
      • name string
      • title string
      • description string
    • checkedAt date-time
    • owner object or null
      Fields of owner
      • id uuid
      • name string
    • 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

  • name string required

    Its tools reach the agent as <name>__<tool>

  • url uri required

    up to 500 characters

  • description string

    up to 500 characters

  • auth "header" or "oauth"

    default "header"

  • authorization string

    1 to 2,000 characters

Answer 201

  • id uuid
  • name string
  • description string
  • url string
  • hasAuthorization boolean
  • auth "header" or "oauth"
  • signedIn boolean
  • tools array of object
    Fields of tools
    • name string
    • title string
    • description string
  • checkedAt date-time
  • owner object or null
    Fields of owner
    • id uuid
    • name string
  • visibility "org" or "private"

GET /api/library/mcp/{id}/agents

The person's agents that have the server.

Path

  • id uuid required

Answer 200

  • agents array of object
    Fields of agents
    • id uuid
    • name string

PATCH /api/library/mcp/{id}

Changes the person's own server; null removes its Authorization header.

Path

  • id uuid required

Body

  • url uri

    up to 500 characters

  • description string

    up to 500 characters

  • authorization string or null

    1 to 2,000 characters

Answer 200

  • id uuid
  • name string
  • description string
  • url string
  • hasAuthorization boolean
  • auth "header" or "oauth"
  • signedIn boolean
  • tools array of object
    Fields of tools
    • name string
    • title string
    • description string
  • checkedAt date-time
  • owner object or null
    Fields of owner
    • id uuid
    • name string
  • 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

  • id uuid required

Answer 204

null

POST /api/library/mcp/{id}/check

Asks the server for its tools again and keeps the answer.

Path

  • id uuid required

Answer 200

  • id uuid
  • name string
  • description string
  • url string
  • hasAuthorization boolean
  • auth "header" or "oauth"
  • signedIn boolean
  • tools array of object
    Fields of tools
    • name string
    • title string
    • description string
  • checkedAt date-time
  • owner object or null
    Fields of owner
    • id uuid
    • name string
  • 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

  • id uuid required

Answer 200

  • url string

DELETE /api/library/mcp/{id}/sign-in

Signs the person out of a server; their agents lose its tools until they sign in.

Path

  • id uuid required

Answer 204

null

GET /api/library/mcp/oauth/callback

Where the browser comes back from an OAuth sign-in.

No sign-in.

Query

  • code string

    up to 4,000 characters

  • state string

    up to 200 characters

  • error string

    up to 200 characters

  • error_description string

    up to 500 characters

Answer

200.

POST /api/library/mcp/{id}/share

Shares a server with everyone.

Path

  • id uuid required

Answer 200

  • id uuid
  • name string
  • description string
  • url string
  • hasAuthorization boolean
  • auth "header" or "oauth"
  • signedIn boolean
  • tools array of object
    Fields of tools
    • name string
    • title string
    • description string
  • checkedAt date-time
  • owner object or null
    Fields of owner
    • id uuid
    • name string
  • visibility "org" or "private"

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

  • connections array of object
    Fields of connections
    • id uuid
    • project object
      Fields of project
      • id uuid
      • name string
    • agent object or null
      Fields of agent
      • id uuid
      • name string
    • kind "github" or "gitlab" or "jira"
    • config object
    • host string
    • namespace string
    • accountLogin string or null
    • lastTestedAt date-time or null
    • syncedAt date-time or null
    • syncError string or null
    • createdAt date-time

POST /api/connections

Connects a project to a code host with a token.

Body

  • projectId uuid required
  • agentId uuid
  • config any required
  • token string required

    1 to 500 characters

Answer 201

  • id uuid
  • project object
    Fields of project
    • id uuid
    • name string
  • agent object or null
    Fields of agent
    • id uuid
    • name string
  • kind "github" or "gitlab" or "jira"
  • config object
  • host string
  • namespace string
  • accountLogin string or null
  • lastTestedAt date-time or null
  • syncedAt date-time or null
  • syncError string or null
  • createdAt date-time

GET /api/connections/{id}

One connection.

Path

  • id uuid required

Answer 200

  • id uuid
  • project object
    Fields of project
    • id uuid
    • name string
  • agent object or null
    Fields of agent
    • id uuid
    • name string
  • kind "github" or "gitlab" or "jira"
  • config object
  • host string
  • namespace string
  • accountLogin string or null
  • lastTestedAt date-time or null
  • syncedAt date-time or null
  • syncError string or null
  • createdAt date-time

PATCH /api/connections/{id}

Changes where a connection reaches, or replaces its token.

Path

  • id uuid required

Body

  • config any
  • token string

    1 to 500 characters

Answer 200

  • id uuid
  • project object
    Fields of project
    • id uuid
    • name string
  • agent object or null
    Fields of agent
    • id uuid
    • name string
  • kind "github" or "gitlab" or "jira"
  • config object
  • host string
  • namespace string
  • accountLogin string or null
  • lastTestedAt date-time or null
  • syncedAt date-time or null
  • syncError string or null
  • createdAt date-time

DELETE /api/connections/{id}

Removes a connection and its token.

Path

  • id uuid required

Answer

200.

POST /api/connections/{id}/test

Asks the host whose token this is.

Path

  • id uuid required

Answer 200

  • login string
  • testedAt date-time

POST /api/connections/{id}/sync

Polls a Jira connection now, without waiting for the interval.

Path

  • id uuid required

Answer 200

  • imported number
  • updated number

GET /api/connections/{id}/webhook

The URL and secret for the host's webhook settings.

Path

  • id uuid required

Answer 200

  • url uri
  • secret string

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" required
  • connectionId uuid 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

  • connections array of object
    Fields of connections
    • id uuid
    • name string
    • kind "anthropic" or "openai" or "gateway"
    • baseUrl string
    • models array of object
      Fields of models
      • id string
      • engine "claude-code" or "codex"
    • checkedAt date-time or null
    • createdAt date-time

POST /api/model-connections

Adds a model connection once its key lists its models.

Body

  • name string required

    1 to 100 characters

  • kind "anthropic" or "openai" or "gateway" required
  • baseUrl uri

    up to 500 characters

  • key string required

    1 to 4,096 characters

Answer 201

  • id uuid
  • name string
  • kind "anthropic" or "openai" or "gateway"
  • baseUrl string
  • models array of object
    Fields of models
    • id string
    • engine "claude-code" or "codex"
  • checkedAt date-time or null
  • createdAt date-time

GET /api/models

The models agents may work with on the server, by connection.

Answer 200

  • connections array of object
    Fields of connections
    • id uuid
    • name string
    • models array of object
      Fields of models
      • id string
      • engine "claude-code" or "codex"

PATCH /api/model-connections/{id}

Renames a model connection, or changes its address or key.

Path

  • id uuid required

Body

  • name string

    1 to 100 characters

  • baseUrl uri

    up to 500 characters

  • key string

    1 to 4,096 characters

Answer 200

  • id uuid
  • name string
  • kind "anthropic" or "openai" or "gateway"
  • baseUrl string
  • models array of object
    Fields of models
    • id string
    • engine "claude-code" or "codex"
  • checkedAt date-time or null
  • createdAt date-time

DELETE /api/model-connections/{id}

Removes a model connection and its key.

Path

  • id uuid required

Answer

200.

POST /api/model-connections/{id}/check

Reads the models of a connection again.

Path

  • id uuid required

Answer 200

  • id uuid
  • name string
  • kind "anthropic" or "openai" or "gateway"
  • baseUrl string
  • models array of object
    Fields of models
    • id string
    • engine "claude-code" or "codex"
  • checkedAt date-time or null
  • createdAt date-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

  • code string
  • expiresAt date-time
  • command string
  • windowsCommand string or null
  • checkout boolean

GET /api/seats

The signed-in user's seats; every seat for an admin.

Answer 200

An array of:

  • id uuid
  • name string
  • owner object
    Fields of owner
    • id uuid
    • name string
  • kind "subscription-laptop" or "api-server" or "local-model" or "subscription-server"
  • status "active" or "revoked"
  • lastSeenAt date-time or null
  • idleMinutes integer

    5 to 120

  • activeRun object or null
    Fields of activeRun
    • id uuid
    • agentName string
    • startedAt date-time or null
  • updateCommand string or null
  • signedOut array of "claude-code" or "codex"
  • platform string or null
  • sandbox object
    Fields of sandbox
    • none boolean
    • allowedAt date-time or null

PATCH /api/seats/{id}

Changes a seat's name or its idle time.

Path

  • id uuid required

Body

  • name string

    1 to 100 characters

  • idleMinutes integer

    5 to 120

Answer 200

  • id uuid
  • name string
  • owner object
    Fields of owner
    • id uuid
    • name string
  • kind "subscription-laptop" or "api-server" or "local-model" or "subscription-server"
  • status "active" or "revoked"
  • lastSeenAt date-time or null
  • idleMinutes integer

    5 to 120

  • activeRun object or null
    Fields of activeRun
    • id uuid
    • agentName string
    • startedAt date-time or null
  • updateCommand string or null
  • signedOut array of "claude-code" or "codex"
  • platform string or null
  • sandbox object
    Fields of sandbox
    • none boolean
    • allowedAt date-time or null

DELETE /api/seats/{id}

Revokes a seat and stops its run.

Path

  • id uuid 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

  • id uuid required

Body

  • allowed boolean required

Answer 200

  • id uuid
  • name string
  • owner object
    Fields of owner
    • id uuid
    • name string
  • kind "subscription-laptop" or "api-server" or "local-model" or "subscription-server"
  • status "active" or "revoked"
  • lastSeenAt date-time or null
  • idleMinutes integer

    5 to 120

  • activeRun object or null
    Fields of activeRun
    • id uuid
    • agentName string
    • startedAt date-time or null
  • updateCommand string or null
  • signedOut array of "claude-code" or "codex"
  • platform string or null
  • sandbox object
    Fields of sandbox
    • none boolean
    • allowedAt date-time or null

POST /api/seats/{id}/remove

Takes a revoked seat off the list; its runs still name it.

Path

  • id uuid 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

  • available boolean
  • computers boolean
  • place object or null
    Fields of place
    • seatId uuid or null
    • state "none" or "asleep" or "awake" or "unknown"
    • signedOut array of string
    • lastSeenAt date-time or null
    • agents array of object
      Fields of agents
      • id uuid
      • name string
    • disk object or null
      Fields of disk
      • usedBytes number
      • limitBytes number

POST /api/me/place

Makes a place on the server for the signed-in person, and connects it.

Answer 201

  • available boolean
  • computers boolean
  • place object or null
    Fields of place
    • seatId uuid or null
    • state "none" or "asleep" or "awake" or "unknown"
    • signedOut array of string
    • lastSeenAt date-time or null
    • agents array of object
      Fields of agents
      • id uuid
      • name string
    • disk object or null
      Fields of disk
      • usedBytes number
      • limitBytes number

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

  • available boolean
  • computers boolean
  • place object or null
    Fields of place
    • seatId uuid or null
    • state "none" or "asleep" or "awake" or "unknown"
    • signedOut array of string
    • lastSeenAt date-time or null
    • agents array of object
      Fields of agents
      • id uuid
      • name string
    • disk object or null
      Fields of disk
      • usedBytes number
      • limitBytes number

POST /api/me/place/sleep

Puts the signed-in person's place to sleep.

Answer 200

  • available boolean
  • computers boolean
  • place object or null
    Fields of place
    • seatId uuid or null
    • state "none" or "asleep" or "awake" or "unknown"
    • signedOut array of string
    • lastSeenAt date-time or null
    • agents array of object
      Fields of agents
      • id uuid
      • name string
    • disk object or null
      Fields of disk
      • usedBytes number
      • limitBytes number

DELETE /api/me/place/folders/{agentId}

Empties an agent's working folders in the signed-in person's place.

Path

  • agentId uuid required

Answer 204

null

You

The signed-in person: their name, API tokens and notifications.

GET /api/me

The signed-in person.

Answer 200

  • id uuid
  • name string
  • email string
  • role "admin" or "member"

PATCH /api/me

Renames the signed-in person or changes their email.

Body

  • name string

    1 to 100 characters

  • email email

    up to 254 characters

  • currentPassword string

    up to 128 characters

Answer 200

  • id uuid
  • name string
  • email string
  • role "admin" or "member"

GET /api/me/two-factor

Whether the signed-in person's password sign-in asks for a code.

Answer 200

  • available boolean
  • enabled boolean

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

  • tokens array of object
    Fields of tokens
    • id uuid
    • name string

      1 to 80 characters

    • scope "read" or "write"
    • createdAt date-time
    • expiresAt date-time or null
    • lastUsedAt date-time or null

POST /api/me/tokens

Creates a token that acts as the person; the token is in this answer only.

Body

  • name string required

    1 to 80 characters

  • scope "read" or "write"

    read: the token passes only requests that read; default "write"

  • expiresInDays integer or null

    Days until the token stops working, up to a year; null never expires; 1 to 365; default 30

Answer 201

  • id uuid
  • name string

    1 to 80 characters

  • scope "read" or "write"
  • createdAt date-time
  • expiresAt date-time or null
  • lastUsedAt date-time or null
  • token string

DELETE /api/me/tokens/{id}

Revokes a token; whatever holds it is signed out at once.

Path

  • id uuid required

Answer 204

null

GET /api/me/push

The server's public VAPID key, for a browser to subscribe with.

Answer 200

  • publicKey string

PUT /api/me/push/subscriptions

Turns notifications on for this browser: its push subscription, as it is.

Body

  • endpoint string required

    up to 2,048 characters

  • keys object required
    Fields of keys
    • p256dh string required
    • auth string required

Answer 204

null

DELETE /api/me/push/subscriptions

Turns notifications off for this browser.

Body

  • endpoint string required

    up 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

  • sent integer

People

Accounts, invitations and handing work over.

GET /api/users

Everyone with an account.

Answer 200

  • users array of object
    Fields of users
    • id uuid
    • name string
    • email string
    • role "admin" or "member"
    • disabledAt string or null
    • createdAt string

GET /api/people

The names of the people who can be given an agent: everyone not disabled.

Answer 200

  • people array of object
    Fields of people
    • id uuid
    • name string

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

  • id uuid required

Body

  • to uuid required

Answer 200

  • transferred array of object
    Fields of transferred
    • id uuid
    • name string
  • returned array of object
    Fields of returned
    • id uuid
    • name string
  • to object
    Fields of to
    • id uuid
    • name string

PATCH /api/users/{id}

Disables or enables a person; disabling signs them out everywhere.

Path

  • id uuid required

Body

  • disabled boolean required

Answer 200

  • id uuid
  • name string
  • email string
  • role "admin" or "member"
  • disabledAt string or null
  • createdAt string

POST /api/invitations

Creates an invitation link; the link is in this answer only.

Body

  • role "admin" or "member"

    default "member"

  • email email

    up to 254 characters

Answer 201

  • id uuid
  • url string
  • expiresAt string

GET /api/invitations

Invitations that can still be accepted.

Answer 200

  • invitations array of object
    Fields of invitations
    • id uuid
    • role "admin" or "member"
    • email string or null
    • invitedBy string
    • createdAt string
    • expiresAt string

DELETE /api/invitations/{id}

Revokes an invitation.

Path

  • id uuid required

Answer

200.

GET /api/invitations/{token}

Whether an invitation link can still be used, and for which role.

No sign-in.

Path

  • token string required

    up to 100 characters

Answer 200

  • valid boolean
  • reason "unknown" or "expired" or "revoked" or "accepted" optional
  • role "admin" or "member" optional
  • email string or null optional
  • invitedBy string optional
  • orgName string optional

POST /api/invitations/{token}/accept

Creates the account an invitation is for, and signs the person in.

No sign-in.

Path

  • token string required

    up to 100 characters

Body

  • name string required

    1 to 100 characters

  • email email required

    up to 254 characters

  • password string required

    12 to 128 characters

Answer 201

  • id uuid
  • name string
  • email string
  • role "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

  • id uuid 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

  • completed boolean
  • keycloak boolean
  • password boolean

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

  • code string required

    up to 64 characters

  • orgName string required

    1 to 100 characters

  • baseUrl uri
  • admin object required
    Fields of admin
    • name string required

      1 to 100 characters

    • email email required

      up to 254 characters

    • password string required

      12 to 128 characters

Answer 201

  • id uuid
  • name string
  • email string
  • role "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"
  • run uuid
  • trace string

    up to 64 characters

  • q string

    up to 200 characters

  • before integer
  • after integer
  • limit integer

    1 to 500; default 100

Answer 200

  • entries array of object
    Fields of entries
    • id number
    • at date-time
    • level number
    • source "server" or "worker"
    • message string
    • context any or null
    • traceId string or null
    • runId uuid or null
    • seatId uuid or null
    • span string or null
    • durationMs number or null
  • nextBefore number 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

  • id string required

    1 to 64 characters

Answer 200

  • traceId string
  • entries array of object
    Fields of entries
    • id number
    • at date-time
    • level number
    • source "server" or "worker"
    • message string
    • context any or null
    • traceId string or null
    • runId uuid or null
    • seatId uuid or null
    • span string or null
    • durationMs number 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"
  • enterprise boolean
  • installationId string
  • id string or null
  • company string or null
  • expiresAt date-time or null
  • graceEndsAt date-time or null
  • agents object
    Fields of agents
    • limit integer or null
    • active integer
    • peak integer
  • over array 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

  • key string required

    1 to 4,000 characters

Answer 200

  • status "free" or "valid" or "grace" or "read_only"
  • enterprise boolean
  • installationId string
  • id string or null
  • company string or null
  • expiresAt date-time or null
  • graceEndsAt date-time or null
  • agents object
    Fields of agents
    • limit integer or null
    • active integer
    • peak integer
  • over array 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

  • version string or null
  • commit string or null
  • updateCheck boolean

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

  • code string required

    up to 64 characters

  • name string required

    1 to 100 characters

  • kind "subscription-laptop" or "api-server" or "local-model" or "subscription-server" required
  • engines array of "claude-code" or "codex" required

    up to 8 items

  • capabilities object

    default {}

    Fields of capabilities
    • docker boolean
    • sandbox boolean

Answer 201

  • seatId uuid
  • token string

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

  • wait integer

    0 to 25; default 25

  • engines string

    up to 200 characters

  • signedOut string

    up to 200 characters

  • worker string
  • platform string

Answer 200

  • run object
    Fields of run
    • id uuid
    • token string
    • limits object
      Fields of limits
      • maxMinutes integer
      • maxTurns integer
      • maxTokens integer
  • agent object
    Fields of agent
    • id uuid
    • name string
    • roleTitle string
    • instructions string
    • engine "claude-code" or "codex"
    • modelPref string or null
    • skills array of object
      Fields of skills
      • name string
      • version integer
      • content string
    • memoryDocuments array of object
      Fields of memoryDocuments
      • path string
      • version integer
      • content string
  • team object optional
    Fields of team
    • mode "auto" or "manual"
    • members array of object
      Fields of members
      • key string
      • agentId uuid
      • name string
      • description string
      • prompt string
      • modelPref string or null
      • token string
      • skills array of object
        Fields of skills
        • name string
        • version integer
        • content string
      • memoryDocuments array of object
        Fields of memoryDocuments
        • path string
        • version integer
        • content string
    • steps array of object
      Fields of steps
      • members array of string
      • note string
  • task object or null
    Fields of task
    • id uuid
    • title string
    • body string
    • repository string or null
  • model object optional
    Fields of model
    • kind "anthropic" or "openai" or "gateway"
    • baseUrl string
    • key string
  • workspace object
    Fields of workspace
    • mcp object
      Fields of mcp
      • url string
    • git object optional
      Fields of git
      • url string
      • username string
      • password string
    • services array of string optional
    • profile object
      Fields of profile
      • claudeMd string
      • projectMd string optional
      • settings object
        Fields of settings
        • permissionMode "acceptEdits"
        • allowedTools array of string
        • sandbox object
          Fields of sandbox
          • enabled boolean
          • failIfUnavailable boolean
          • autoAllowBashIfSandboxed boolean
          • allowUnsandboxedCommands false
          • network object
            Fields of network
            • allowedDomains array of string
            • strictAllowlist true
            • allowLocalBinding true 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

  • lines array of object required

    up to 500 items

    Fields of lines
    • at date-time required
    • level "info" or "warn" or "error" required
    • message string required

      up to 4,000 characters

    • runId uuid

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

  • id uuid required

Body

An array of:

  • seq integer required
  • type string required

    1 to 64 characters

  • payload object required
  • at date-time required

Answer 200

  • accepted integer
  • cancelRequested boolean

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

  • id uuid required

Answer 200

  • cancelRequested boolean
  • waitedMs integer

POST /api/runs/{id}/finish

Ends a run with its summary, artifacts and usage.

With a seat’s or a run’s token.

Path

  • id uuid required

Body

  • status "done" or "failed" or "cancelled" required
  • summary string

    up to 20,000 characters

  • errorCode string

    1 to 64 characters

  • artifacts array of object

    up to 100 items; default []

    Fields of artifacts
    • kind "branch" or "file" or "report" required
    • ref string required

      1 to 2,000 characters

    • meta object

      default {}

  • usage array of object

    up to 100 items; default []

    Fields of usage
    • provider string required

      1 to 64 characters

    • model string required

      1 to 200 characters

    • tokensIn integer required
    • tokensOut integer required
    • tokensCacheRead integer required
    • tokensCacheWrite integer required
    • tokensCacheWrite1h integer

      default 0

    • source string required

      1 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

  • id uuid required

Body

  • folder string

    up to 200 characters

Answer 200

  • cli object
    Fields of cli
    • host string

      1 to 253 characters

    • port integer

      1 to 65,535

    • key string

      32 to 128 characters

  • sandbox object
    Fields of sandbox
    • host string

      1 to 253 characters

    • port integer

      1 to 65,535

    • key string

      32 to 128 characters

  • docker boolean optional
  • cliToken string

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

  • id uuid required

Answer 204

null