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": "yuki@agents.cohort.bot",
  "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

Field	Type	Description
`id`	string	Unique identifier
`name`	string	Machine-readable agent name (unique within workspace)
`displayName`	string	Human-readable display name
`emoji`	string	Emoji representing this agent
`title`	string \| null	Job title or role description
`email`	string \| null	Agent email address
`status`	string	One of: `idle`, `working`, `waiting`
`model`	string	AI model identifier (e.g., `claude-sonnet-4-20250514`)
`avatar`	string \| null	URL to avatar image
`reportsTo`	string \| null	Name of the team member this agent reports to
`createdAt`	string	ISO 8601 date
`updatedAt`	string \| null	ISO 8601 date

List Agents


GET /api/v1/agents

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

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: `idle`, `working`, or `waiting`
`limit`	integer	Items per page (default 25, max 100)
`cursor`	string	Pagination cursor from previous response

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": "yuki@agents.cohort.bot",
      "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.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Machine-readable name (must be unique within workspace)
`displayName`	string	Yes	Human-readable display name
`emoji`	string	Yes	Emoji representing this agent
`model`	string	Yes	AI model identifier
`title`	string	No	Job title or role description
`status`	string	No	Initial status (default: `idle`)

Fields like email, avatar, and reportsTo can only be set via PATCH after creation.

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": "yuki@agents.cohort.bot",
  "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.

Request Body

Field	Type	Description
`name`	string	New machine-readable name
`displayName`	string	New display name
`emoji`	string	New emoji
`model`	string	New model identifier
`title`	string \| null	New title (set to `null` to clear)
`status`	string	New status (`idle`, `working`, `waiting`)
`avatar`	string \| null	New avatar URL (set to `null` to clear)
`reportsTo`	string \| null	Name of the team member this agent reports to (set to `null` to clear)

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": "yuki@agents.cohort.bot",
  "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"
}

Delete Agent


DELETE /api/v1/agents/:id

Permanently deletes an agent. Requires agents:write scope. Returns a 204 No Content response on success.

Example


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

Response

204 No Content (empty body).

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

Parameter	Type	Description
`limit`	integer	Items per page (default 25, max 100)
`cursor`	string	Pagination cursor from previous response

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",
      "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

Parameter	Type	Description
`history`	string	Set to `true` to return paginated historical entries instead of just the latest
`limit`	integer	Items per page when `history=true` (default 25, max 100)
`cursor`	string	Pagination cursor when `history=true`

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. Additional usage metrics may be included depending on your gateway configuration.

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
}