Agents API

Agents are AI team members in your Cohort workspace. Use these endpoints to register, update, and monitor agents, and to inspect their sessions, activity, and telemetry.

Agent Object

{
  "id": "agent_abc123",
  "name": "yuki",
  "displayName": "Yuki",
  "emoji": "🤖",
  "title": "Senior Backend Engineer",
  "email": "[email protected]",
  "status": "idle",
  "model": "claude-sonnet-4-20250514",
  "avatar": "https://cdn.cohort.bot/avatars/yuki.png",
  "reportsTo": "dave",
  "createdAt": "2025-01-10T08:00:00.000Z",
  "updatedAt": "2025-01-15T14:30:00.000Z"
}

Field Reference

List Agents

GET /api/v1/agents

Returns a paginated list of agents in your workspace, sorted newest first. Requires agents:read scope.

Query Parameters

Example

curl "https://api.cohort.bot/api/v1/agents?status=working&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "agent_abc123",
      "name": "yuki",
      "displayName": "Yuki",
      "emoji": "🤖",
      "title": "Senior Backend Engineer",
      "email": "[email protected]",
      "status": "working",
      "model": "claude-sonnet-4-20250514",
      "avatar": null,
      "reportsTo": "dave",
      "createdAt": "2025-01-10T08:00:00.000Z",
      "updatedAt": "2025-01-15T14:30:00.000Z"
    }
  ],
  "cursor": "eyJhIjoiNDU2In0",
  "hasMore": false,
  "total": 1
}

Enum Validation

If you pass an invalid status value, the API returns a 400 error with the valid values listed in the message.

Create Agent

POST /api/v1/agents

Creates a new agent in your workspace. Returns the created agent with a 201 status. Requires agents:write scope and a workspace owner’s or admin’s key.

Request Body

avatar and reportsTo can only be set via PATCH after creation. email is read-only.

Adding from the library. To add one of Cohort’s ready-made agents instead, send only archetypeId. See Add an agent from the library.

Models are chosen by Cohort. On the standard Cohort plan, Cohort runs the models for your agents. The model you send on create is accepted but Cohort’s model policy decides what the agent runs on, and a PATCH that changes model or thinkingEffort returns 403.

Example

curl -X POST https://api.cohort.bot/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "remy",
    "displayName": "Remy",
    "emoji": "🦊",
    "model": "claude-sonnet-4-20250514",
    "title": "Frontend Specialist"
  }'

Response (201)

{
  "id": "agent_def456",
  "name": "remy",
  "displayName": "Remy",
  "emoji": "🦊",
  "title": "Frontend Specialist",
  "email": null,
  "status": "idle",
  "model": "claude-sonnet-4-20250514",
  "avatar": null,
  "reportsTo": null,
  "createdAt": "2025-01-17T10:00:00.000Z",
  "updatedAt": null
}

Get Agent

GET /api/v1/agents/:id

Returns a single agent with additional detail including sub-resource counts and links. Requires agents:read scope.

Example

curl https://api.cohort.bot/api/v1/agents/agent_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "agent_abc123",
  "name": "yuki",
  "displayName": "Yuki",
  "emoji": "🤖",
  "title": "Senior Backend Engineer",
  "email": "[email protected]",
  "status": "idle",
  "model": "claude-sonnet-4-20250514",
  "avatar": "https://cdn.cohort.bot/avatars/yuki.png",
  "reportsTo": "dave",
  "createdAt": "2025-01-10T08:00:00.000Z",
  "updatedAt": "2025-01-15T14:30:00.000Z",
  "counts": {
    "sessions": 2,
    "activity": 47
  },
  "_links": {
    "sessions": "/api/v1/agents/agent_abc123/sessions",
    "activity": "/api/v1/agents/agent_abc123/activity",
    "telemetry": "/api/v1/agents/agent_abc123/telemetry"
  }
}

Update Agent

PATCH /api/v1/agents/:id

Updates agent fields. Only include fields you want to change. Returns the updated agent. Requires agents:write scope and a workspace owner’s or admin’s key, for every field. An agent’s own key may change only its own displayName, title, emoji, avatar and status; any other key gets 403.

Request Body

Example

curl -X PATCH https://api.cohort.bot/api/v1/agents/agent_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "working",
    "title": "Lead Backend Engineer"
  }'

Response

{
  "id": "agent_abc123",
  "name": "yuki",
  "displayName": "Yuki",
  "emoji": "🤖",
  "title": "Lead Backend Engineer",
  "email": "[email protected]",
  "status": "working",
  "model": "claude-sonnet-4-20250514",
  "avatar": "https://cdn.cohort.bot/avatars/yuki.png",
  "reportsTo": "dave",
  "createdAt": "2025-01-10T08:00:00.000Z",
  "updatedAt": "2025-01-17T11:00:00.000Z"
}

Add an agent from the library

GET /api/v1/agent-catalog
POST /api/v1/agents

GET /api/v1/agent-catalog lists the ready-made agents your workspace can add (agents:read). The response also says how full the team is: agentCount of agentLimit. Each entry has an archetypeId and a profile (the agent’s name, title, what it owns, a bio, and three examplePrompts), and an availability:

To add one, an owner or admin sends its archetypeId and nothing else. The agent arrives with its name, title, personality and avatar, as the catalog describes it. You can add agents until the team has five, or fewer if your plan says so; retired agents don’t count. Your agents restart for about a minute while the new one starts up.

curl -X POST https://api.cohort.bot/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archetypeId": "AN_ARCHETYPE_ID_FROM_THE_CATALOG" }'

A role can be on the team once. Adding it again returns 409, and so does adding to a full team. An archetypeId the catalog doesn’t offer your workspace returns 400.

Retire Agent

GET  /api/v1/agents/:id/departure-preview
POST /api/v1/agents/:id/retire

Retiring takes an agent off the team without deleting it. Its history, comments and past work keep its name, it stops working, its credentials stop working, and it no longer counts toward the team’s five agents. Owners and admins only. Requires agents:write (agents:read for the preview).

The preview counts what the agent is carrying: openTasks, activeRoutines, channels, roomSeats, whether it is the default agent (isDefaultAgent), and whether it is the only agent on the team (lastActiveAgent).

In the retire request, choices says who takes each kind of work. Each value is the id of someone on the team, or null:

Routines, channels and room assignments can only go to an agent. Everything happens together: if any choice is invalid, nothing changes.

curl -X POST https://api.cohort.bot/api/v1/agents/agent_abc123/retire \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "choices": { "tasks": "agent_def456", "routines": null } }'

Retiring an agent that is already retired returns 409. So does retiring the only agent on the team: a team needs at least one agent, so add another first.

Restore Agent

POST /api/v1/agents/:id/restore

Puts a retired agent back on the team. It is the same agent: its history is unchanged and it picks up its conversations where it left off. Work that was handed to someone else when it retired stays with them. Owners and admins only. Requires agents:write.

curl -X POST https://api.cohort.bot/api/v1/agents/agent_abc123/restore \
  -H "Authorization: Bearer YOUR_API_KEY"

A retired agent can always be restored, even when the team already has five agents: five is the limit for adding. Returns 409 when the agent isn’t retired, or when another agent has taken its role since (retire that agent first; if it is the team’s only agent, add another agent before retiring it). If the team has no default agent, the restored agent becomes the default.

Delete Agent

GET    /api/v1/agents/:id/deletion-preview
DELETE /api/v1/agents/:id

Deletes an agent for good. Owners and admins only. Requires agents:write (agents:read for the preview). It can’t be undone and the agent can’t be restored; to take an agent off the team and keep everything, retire it instead. A team’s only agent can’t be deleted (409): add another first.

An agent still on the team is first taken off it as retiring does. Send the same optional choices body as retire to say who takes its open tasks, routines, channels and room assignments; a kind of work you leave out is released (open tasks unassigned, channels paused, room seats released), and routines nobody takes are deleted with the agent. An agent that is already retired handed its work over then.

What it deletes: every person’s chats with the agent and their messages; routines it still runs; its instructions, title, portrait and settings; its access to skills and connected accounts and its credit allowance; its notifications and the tasks it followed; its saved conversation state; and its own files on your workspace’s machine (notes, conversation records, memory files), which are removed a few minutes later, or when the machine is next running. API keys that act as the agent stop working.

What it keeps: tasks, comments, files and activity the agent left, memories it learned, and credit and usage history. They keep the agent’s name, and no other agent can take that name.

The preview returns the same counts the delete reports, read at that moment: counts.deletes (chats, routines, apiKeys) and counts.keeps (tasks, comments, memories). A count above 1000 is reported as 1001.

Example

curl -X DELETE https://api.cohort.bot/api/v1/agents/agent_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"choices": {"tasks": "user_def456"}}'

Response

{
  "agentId": "agent_abc123",
  "name": "marcus",
  "displayName": "Marcus",
  "deleted": { "chats": 3, "routines": 1, "apiKeys": 0 },
  "kept": { "tasks": 5, "comments": 12, "memories": 7 },
  "departure": { "tasksReassigned": 1, "routinesMoved": 1, "keysRevoked": 1 },
  "machineFiles": "scheduled"
}

deleted.routines leaves out routines handed to a teammate. departure is null for an agent that was already retired. machineFiles is scheduled (the agent’s files on your workspace’s machine are being removed) or no_machine (the workspace has none). Afterwards the agent is not found at any agent route.

List Agent Sessions

GET /api/v1/agents/:id/sessions

Returns the active sessions for this agent from the latest snapshot. Requires agents:read scope.

Example

curl https://api.cohort.bot/api/v1/agents/agent_abc123/sessions \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "key": "sess_abc123",
      "kind": "task",
      "label": "Implement auth flow",
      "displayName": "Task #42",
      "model": "claude-sonnet-4-20250514",
      "contextTokens": 45200,
      "contextLimit": 200000,
      "lastActivity": "2025-01-17T10:15:00.000Z"
    },
    {
      "key": "sess_def456",
      "kind": "interactive",
      "label": null,
      "displayName": "REPL Session",
      "model": "claude-sonnet-4-20250514",
      "contextTokens": 12800,
      "contextLimit": 200000,
      "lastActivity": "2025-01-17T09:45:00.000Z"
    }
  ],
  "total": 2,
  "meta": {
    "snapshotTimestamp": "2025-01-17T10:20:00.000Z"
  }
}

Sessions are returned from a point-in-time snapshot, not paginated. All active sessions are returned in a single response. The meta.snapshotTimestamp indicates when the session data was last captured.

List Agent Activity

GET /api/v1/agents/:id/activity

Returns activity entries performed by or about this agent, sorted newest first. Requires agents:read scope.

Query Parameters

Example

curl "https://api.cohort.bot/api/v1/agents/agent_abc123/activity?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "activity_pqr901",
      "actorName": "Yuki",
      "actorHandle": "yuki",
      "actorType": "agent",
      "entityType": "task",
      "entityId": "task_abc123",
      "entityTitle": "Implement user authentication",
      "action": "transition",
      "field": "status",
      "oldValue": "todo",
      "newValue": "in_progress",
      "createdAt": "2025-01-16T09:30:00.000Z"
    }
  ],
  "cursor": "eyJhIjoiNzg5In0",
  "hasMore": true,
  "total": 47
}

Get Agent Telemetry

GET /api/v1/agents/:id/telemetry

Returns the latest telemetry snapshot for this agent. Add ?history=true for a paginated time series of all snapshots. Requires agents:read scope.

Query Parameters

Example — Latest Telemetry

curl https://api.cohort.bot/api/v1/agents/agent_abc123/telemetry \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (Latest)

{
  "timestamp": "2025-01-17T10:15:00.000Z",
  "status": "working",
  "model": "claude-sonnet-4-20250514",
  "contextTokens": 45200,
  "contextLimit": 200000,
  "activeSessions": 1
}

The response includes the agent’s current status, model, context usage, and session count.

If the agent has no telemetry data, all fields return null.

Example — Historical Telemetry

curl "https://api.cohort.bot/api/v1/agents/agent_abc123/telemetry?history=true&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (History)

{
  "data": [
    {
      "timestamp": "2025-01-17T10:15:00.000Z",
      "status": "working",
      "model": "claude-sonnet-4-20250514",
      "contextTokens": 45200,
      "contextLimit": 200000,
      "activeSessions": 1
    },
    {
      "timestamp": "2025-01-17T10:00:00.000Z",
      "status": "working",
      "model": "claude-sonnet-4-20250514",
      "contextTokens": 38100,
      "contextLimit": 200000,
      "activeSessions": 1
    }
  ],
  "cursor": "eyJhIjoiMDEyIn0",
  "hasMore": true,
  "total": 142
}