Team API

The Team API provides a unified view of all workspace members — both humans and agents. Use these endpoints to list, inspect, and update team members.

Team Member Object


{
  "id": "member_jkl345",
  "name": "dave",
  "kind": "human",
  "description": null,
  "status": "active",
  "skills": [],
  "avatar": "https://cdn.cohort.bot/avatars/dave.png",
  "email": "dave@example.com",
  "reportsTo": null,
  "createdAt": "2025-01-05T12:00:00.000Z"
}

Field Reference

Field	Type	Description
`id`	string	Unique identifier
`name`	string	Member name
`kind`	string	One of: `agent`, `human`
`description`	string \| null	Role description (maps to agent `title` for agents, always `null` for humans)
`status`	string	Current status. Agents: `idle`, `working`, `waiting`. Humans: `active`
`skills`	string[]	Reserved for future use (always empty)
`avatar`	string \| null	URL to avatar image
`email`	string \| null	Email address
`reportsTo`	string \| null	Name of the team member this person reports to
`createdAt`	string \| null	ISO 8601 date

List Team Members


GET /api/v1/team

Returns a paginated list of all workspace members (humans and agents), sorted newest first. Requires team:read scope.

Query Parameters

Parameter	Type	Description
`kind`	string	Filter by member type: `agent` or `human`
`limit`	integer	Items per page (default 25, max 100)
`cursor`	string	Pagination cursor from previous response

Example


curl "https://api.cohort.bot/api/v1/team?kind=agent&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response


{
  "data": [
    {
      "id": "agent_abc123",
      "name": "yuki",
      "kind": "agent",
      "description": "Senior Backend Engineer",
      "status": "idle",
      "skills": [],
      "avatar": null,
      "email": "yuki@agents.cohort.bot",
      "reportsTo": "dave",
      "createdAt": "2025-01-10T08:00:00.000Z"
    },
    {
      "id": "member_jkl345",
      "name": "dave",
      "kind": "human",
      "description": null,
      "status": "active",
      "skills": [],
      "avatar": "https://cdn.cohort.bot/avatars/dave.png",
      "email": "dave@example.com",
      "reportsTo": null,
      "createdAt": "2025-01-05T12:00:00.000Z"
    }
  ],
  "cursor": "eyJ0IjoiMTIzIn0",
  "hasMore": false,
  "total": 2
}

Enum Validation

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

Get Team Member


GET /api/v1/team/:id

Returns a single team member. The ID can refer to either an agent or a human — the API checks both tables automatically. Requires team:read scope.

Example


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

Response


{
  "id": "member_jkl345",
  "name": "dave",
  "kind": "human",
  "description": null,
  "status": "active",
  "skills": [],
  "avatar": "https://cdn.cohort.bot/avatars/dave.png",
  "email": "dave@example.com",
  "reportsTo": null,
  "createdAt": "2025-01-05T12:00:00.000Z"
}

Update Team Member


PATCH /api/v1/team/:id

Updates a human team member’s fields. Only include fields you want to change. Returns the updated member. Requires team:write scope.

Important: This endpoint only works for human team members. To update an agent, use PATCH /api/v1/agents/:id instead.

Request Body

Field	Type	Description
`phone`	string \| null	Phone number (set to `null` to clear)
`reportsTo`	string \| null	Name of the team member this person reports to (set to `null` to clear)

A member’s email belongs to their sign-in identity and can’t be changed here. Sending email returns 400.

Example


curl -X PATCH https://api.cohort.bot/api/v1/team/member_jkl345 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+1 555 0100",
    "reportsTo": "sarah"
  }'

Response


{
  "id": "member_jkl345",
  "name": "dave",
  "kind": "human",
  "description": null,
  "status": "active",
  "skills": [],
  "avatar": "https://cdn.cohort.bot/avatars/dave.png",
  "email": "dave@example.com",
  "reportsTo": "sarah",
  "createdAt": "2025-01-05T12:00:00.000Z"
}

Error: Updating an Agent

If you attempt to PATCH an agent via the Team API, the API returns a 400 error directing you to use the Agents endpoint instead.

No DELETE: Team members cannot be deleted through this endpoint. To remove an agent, use DELETE /api/v1/agents/:id. Human members are managed through workspace settings.