Agents

Read-only views of the workspace's AI agents: who they are, what they are running and what they have proposed. Runs and proposals are narrowed to the projects and tasks the caller can read.

List agents

GET /api/v2/agents · beta

Lists the workspace's agents, oldest first.

Any signed-in member of the workspace may call it. Answers with data: the agents that are not deleted, oldest first. Each agent's projectIds list is cut to the projects the caller can open, unless the caller is an owner or admin, and projectScoped says whether the agent is limited to projects at all.


Auth	Session or API token with the `read` scope
Token limited to projects	Refused

Request

http

GET /api/v2/agents
Authorization: Bearer <token>
companyid: <company id>

Response

json

{
  "status": true,
  "statusText": "Agents fetched.",
  "data": [
    {
      "_id": "<agent id>",
      "name": "Triage",
      "autonomy": 1,
      "paused": false,
      "skills": ["<skill key>"],
      "spendCapUsd": 20
    }
  ]
}

Each row is the whole stored agent; the example shows some of its fields.

Errors

Status	When
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `read` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

Read the team board

GET /api/v2/agents/team · beta

Returns the people and agents of the workspace, what each is on right now, and a short standup.

Any signed-in member of the workspace may call it. Reads hoursPerWeek (a number above 0, 40 when left out) from the query. Answers with data: the people and agents of the workspace with what each is on, their load for the week, time off, and a standup composed from them.


Auth	Session or API token with the `read` scope
Token limited to projects	Refused

Query parameters

Name	Type	Required	Description
`hoursPerWeek`	number		The weekly capacity each person's load is measured against. 40 when left out.

Request

http

GET /api/v2/agents/team
Authorization: Bearer <token>
companyid: <company id>

Response

json

{
  "status": true,
  "statusText": "Team board fetched.",
  "data": {
    "people": [
      {
        "kind": "person",
        "id": "<user id>",
        "name": "Sample Person",
        "email": "person@example.com",
        "roleType": 3,
        "online": true,
        "timer": null,
        "nowOn": "Write the release notes",
        "openTasks": 4,
        "loggedHours": 12,
        "capacityHours": 40,
        "load": 30,
        "pto": null,
        "status": "available"
      }
    ],
    "agents": [
      {
        "kind": "agent",
        "id": "<agent id>",
        "name": "Triage",
        "ownerId": "<user id>",
        "autonomy": 1,
        "paused": false,
        "skills": ["<skill key>"],
        "allowedActions": [],
        "spend": { "usd": 1.4, "cap": 20, "runs": 9 },
        "run": null,
        "nowOn": "",
        "status": "idle"
      }
    ],
    "activity": [
      {
        "at": "2026-10-01T09:30:00.000Z",
        "kind": "agent",
        "who": "Triage",
        "what": "done",
        "taskId": "<task id>",
        "runId": "<run id>",
        "status": "done"
      }
    ],
    "totals": {
      "people": 1,
      "agents": 1,
      "running": 0,
      "away": 0,
      "load": 30,
      "weekStart": "2026-09-28T00:00:00.000Z"
    },
    "standup": {
      "generatedAt": "2026-10-01T09:30:00.000Z",
      "lines": [
        "Sample Person: next up \"Write the release notes\" · 4 open tasks · 12h logged this week"
      ]
    }
  }
}

A person's status is working, available, away or offline; an agent's is running, paused or idle. Hours and load are null for a caller who may not see other people's time. A task the caller cannot read is shown as hidden, without its name.

The example shows some of the fields of each row.

Errors

Status	When
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `read` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

List agent runs

GET /api/v2/agents/runs · beta

Lists agent runs, newest first, with a summary of the runs that are open now.

Any signed-in member of the workspace may call it. Reads status, projectId, agentId, taskId, errorType and limit from the query; an errorType outside the known provider errors answers 400. Owners and admins see every project's runs, and other members see runs in the projects they can open, except runs on tasks in private lists they are not on. Answers with data (the runs, newest first) and summary (the runs open now).


Auth	Session or API token with the `read` scope
Token limited to projects	Refused

Query parameters

Name	Type	Description
`status`	string	`open` (queued, running or waiting for approval), or one of `queued`, `running`, `waiting_approval`, `done`, `skipped`, `failed`, `stopped`.
`projectId`	id	Runs in that project.
`agentId`	id	Runs of that agent.
`taskId`	id	Runs on that task.
`errorType`	string	Failed runs with that kind of provider error.
`limit`	number	How many runs to return, from 1 to 200. 50 when left out.

Request

http

GET /api/v2/agents/runs?status=open&limit=20
Authorization: Bearer <token>
companyid: <company id>

Response

json

{
  "status": true,
  "statusText": "Runs fetched.",
  "data": [
    {
      "_id": "<run id>",
      "agentId": "<agent id>",
      "agentName": "Triage",
      "taskId": "<task id>",
      "projectId": "<project id>",
      "trigger": "manual",
      "status": "done",
      "startedBy": "<user id>",
      "startedAt": "2026-10-01T09:30:00.000Z",
      "finishedAt": "2026-10-01T09:31:10.000Z",
      "elapsedMs": 70000,
      "spend": { "tokens": 1840, "usd": 0.02 }
    }
  ],
  "summary": {
    "running": 1,
    "waitingApproval": 0,
    "agents": 1,
    "elapsedMs": 42000,
    "spendUsd": 0.01,
    "runs": [
      {
        "_id": "<run id>",
        "agentId": "<agent id>",
        "agentName": "Triage",
        "status": "running",
        "taskId": "<task id>",
        "startedAt": "2026-10-01T09:30:00.000Z",
        "projectId": "<project id>",
        "skill": null,
        "spendUsd": 0.01
      }
    ]
  }
}

summary sits beside data. Each row of data is the whole stored run; the example shows some of its fields.

Paging

Limit only. The newest runs come first and there is no next page; narrow with the filters.

Errors

Status	When
400	`errorType` is not one of the known kinds.
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `read` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

Read an agent run

GET /api/v2/agents/runs/:id · beta

Returns one run with its steps, the audit rows of what it did, and the agent revision it ran on.

Any signed-in member of the workspace who may see the run: for most runs, the people who can open its project and its tasks, and for a run that produced a report, only the person who started it and owners and admins. A run the caller may not see answers 404 as one that does not exist does. Answers with data: the run with its steps, the audit rows of what it did, the revision of the agent it ran on, and a trace.


Auth	Session or API token with the `read` scope
Token limited to projects	Refused

Path parameters

Name	Type	Description
`id`	id	The run.

Request

http

GET /api/v2/agents/runs/<id>
Authorization: Bearer <token>
companyid: <company id>

Response

json

{
  "status": true,
  "statusText": "Run fetched.",
  "data": {
    "run": {
      "_id": "<run id>",
      "agentId": "<agent id>",
      "agentName": "Triage",
      "taskId": "<task id>",
      "projectId": "<project id>",
      "trigger": "manual",
      "status": "done",
      "startedBy": "<user id>",
      "startedAt": "2026-10-01T09:30:00.000Z",
      "finishedAt": "2026-10-01T09:31:10.000Z",
      "elapsedMs": 70000,
      "spend": { "tokens": 1840, "usd": 0.02 },
      "steps": [],
      "agentRevision": 2,
      "undoable": false,
      "undoReason": ""
    },
    "audit": [],
    "revision": { "n": 2, "state": "live" },
    "trace": {}
  }
}

Field	Description
`run`	The stored run, with `steps`, the `agentRevision` it was pinned to, and whether it can still be undone (`undoable`, `undoUntil`, `undoReason`).
`audit`	Up to 200 audit rows the run wrote, oldest first.
`revision`	The agent revision the run used.
`trace`	The run's steps and audit rows arranged for display.

Errors

Status	When
400	The id is not an id.
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `read` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
404	The run does not exist, or the caller cannot see its task. A report run is open only to the person it was made for and to owners and admins.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

List agent proposals

GET /api/v2/agents/proposals · beta

Lists the changes agents have proposed and are waiting on a person for, newest first.

Any signed-in member of the workspace may call it. Reads status (pending when left out, or all, or one status), bucket, agentId and limit from the query. A member sees the proposals of projects they can open, plus ones asked for by their own agents, and owners and admins see every project's. Answers with data (the proposals, newest first) and counts.


Auth	Session or API token with the `read` scope
Token limited to projects	Refused

Query parameters

Name	Type	Description
`status`	string	`pending` when left out. `all`, or one of `pending`, `applying`, `approved`, `edited`, `declined`, `undone`, `failed`.
`bucket`	string	`primary` or `later`.
`agentId`	id	Proposals of that agent.
`limit`	number	How many to return, up to 500. 100 when left out.

Request

http

GET /api/v2/agents/proposals
Authorization: Bearer <token>
companyid: <company id>

Response

json

{
  "status": true,
  "statusText": "Proposals fetched.",
  "data": [
    {
      "_id": "<proposal id>",
      "agentId": "<agent id>",
      "agentName": "Triage",
      "runId": "<run id>",
      "taskId": "<task id>",
      "projectId": "<project id>",
      "what": "Set the priority to High",
      "why": "The customer reported an outage.",
      "changes": [],
      "status": "pending",
      "bucket": "primary",
      "undoAvailable": false,
      "createdAt": "2026-10-01T09:30:00.000Z"
    }
  ],
  "counts": {
    "waiting": 1,
    "doneByAi": 0,
    "declined": 0,
    "undone": 0,
    "failed": 0,
    "primary": 1,
    "later": 0
  }
}

counts sits beside data and is counted over everything the caller can read, whatever status was asked for.

Paging

Limit only. The newest proposals come first and there is no next page.

Errors

Status	When
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `read` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

Agents ​

List agents ​

Read the team board ​

List agent runs ​

Read an agent run ​

List agent proposals ​

Agents

List agents

Read the team board

List agent runs

Read an agent run

List agent proposals