---
sidebar_position: 8
title: Teams
description: Manage agent teams for call routing and workload distribution — create teams, add/remove agents, and query team membership via the Firetell REST API.
---

# Teams

Teams group agents together for call routing, queue management, and workload distribution. Each team can contain multiple agents, and each agent can belong to multiple teams. Team members can have a role of either `leader` or `member`.

## Endpoints

| Method   | Endpoint                       | Description                    |
| -------- | ------------------------------ | ------------------------------ |
| `GET`    | `/teams`                       | List all teams                 |
| `GET`    | `/teams/:id`                   | Get team details               |
| `POST`   | `/teams`                       | Create a team                  |
| `PATCH`  | `/teams/:id`                   | Update a team                  |
| `DELETE` | `/teams/:id`                   | Delete a team                  |
| `GET`    | `/teams/:id/agents`            | List agents in a team          |
| `PUT`    | `/teams/:id/agents/:agent_id`  | Add an agent to a team         |
| `DELETE` | `/teams/:id/agents/:agent_id`  | Remove an agent from a team    |
| `GET`    | `/teams/:id/suggestion-agents` | Suggest agents not in the team |

## The Team Object

| Field          | Type   | Description                                  |
| -------------- | ------ | -------------------------------------------- |
| `id`           | string | Unique team identifier (prefixed with `te_`) |
| `title`        | string | Team name                                    |
| `workspace_id` | string | Workspace identifier                         |
| `agent_count`  | number | Number of agents currently in the team       |
| `created_at`   | string | ISO 8601 creation timestamp                  |
| `updated_at`   | string | ISO 8601 last update timestamp               |

### Team Agent Object

When listing agents within a team, each item contains:

| Field          | Type   | Description                                    |
| -------------- | ------ | ---------------------------------------------- |
| `team_id`      | string | The team ID                                    |
| `agent_id`     | string | The agent ID                                   |
| `workspace_id` | string | Workspace identifier                           |
| `role`         | string | Agent's role in the team: `leader` or `member` |
| `agent`        | object | Populated agent details (see below)            |
| `created_at`   | string | ISO 8601 timestamp when agent joined           |
| `updated_at`   | string | ISO 8601 last update timestamp                 |

The populated `agent` object includes:

| Field          | Type           | Description        |
| -------------- | -------------- | ------------------ |
| `id`           | string         | Agent ID           |
| `display_name` | string         | Agent display name |
| `avatar`       | string \| null | Agent avatar URL   |
| `email`        | string \| null | Agent email        |
| `username`     | string         | Agent username     |
| `country_code` | string         | Agent country code |

---

## List Teams

```
GET /teams
```

Retrieve a paginated list of all teams in the workspace.

### Authentication

Requires `ApiKey` with any scope.

### Query Parameters

| Parameter    | Type   | Default      | Description                                               |
| ------------ | ------ | ------------ | --------------------------------------------------------- |
| `page`       | number | `1`          | Page number (min: 1)                                      |
| `limit`      | number | `10`         | Items per page (min: 1, max: 100)                         |
| `search`     | string | —            | Search teams by title                                     |
| `sort_field` | string | `created_at` | Sort field. Allowed: `created_at`, `title`, `agent_count` |
| `sort_order` | string | `desc`       | Sort order: `asc` or `desc`                               |

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/teams?page=1&limit=10&sort_field=agent_count&sort_order=desc" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

### Response

```json
{
  "data": [
    {
      "id": "te_a1b2c3d4e5f6a7b8c9d0e1f2",
      "title": "Support Team",
      "workspace_id": "yourcompany",
      "agent_count": 12,
      "created_at": "2026-01-10T09:00:00.000Z",
      "updated_at": "2026-03-20T14:00:00.000Z"
    },
    {
      "id": "te_b2c3d4e5f6a7b8c9d0e1f2a3",
      "title": "Sales Team",
      "workspace_id": "yourcompany",
      "agent_count": 8,
      "created_at": "2026-01-12T11:00:00.000Z",
      "updated_at": "2026-02-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}
```

---

## Get Team

```
GET /teams/:id
```

Retrieve details of a specific team.

### Authentication

Requires `ApiKey` with any scope.

### Path Parameters

| Parameter | Type   | Description                                       |
| --------- | ------ | ------------------------------------------------- |
| `id`      | string | The team ID (e.g., `te_a1b2c3d4e5f6a7b8c9d0e1f2`) |

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/teams/te_a1b2c3d4e5f6a7b8c9d0e1f2" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

### Response

```json
{
  "id": "te_a1b2c3d4e5f6a7b8c9d0e1f2",
  "title": "Support Team",
  "workspace_id": "yourcompany",
  "agent_count": 12,
  "created_at": "2026-01-10T09:00:00.000Z",
  "updated_at": "2026-03-20T14:00:00.000Z"
}
```

### Error Response

```json
{
  "statusCode": 404,
  "message": "Team not found or does not belong to this workspace",
  "error": "Not Found"
}
```

---

## Create Team

```
POST /teams
```

Create a new team in the workspace.

### Authentication

Requires `ApiKey` with `full` scope.

:::caution
Each workspace is limited to a maximum of **100 teams**. Exceeding this limit will return a `402 Payment Required` error.
:::

### Request Body

| Field   | Type   | Required | Description                 |
| ------- | ------ | -------- | --------------------------- |
| `title` | string | ✅       | Team name. 1–36 characters. |

### Request

```bash
curl -X POST "https://{workspace_id}.firetell.app/api/v1/teams" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Technical Support"
  }'
```

### Response

```json
{
  "id": "te_c3d4e5f6a7b8c9d0e1f2a3b4",
  "title": "Technical Support",
  "workspace_id": "yourcompany",
  "agent_count": 0,
  "created_at": "2026-07-09T08:00:00.000Z",
  "updated_at": "2026-07-09T08:00:00.000Z"
}
```

### Error Response

**Team limit reached:**

```json
{
  "statusCode": 402,
  "message": "You have reached the maximum limit of 100 team. Please contact support"
}
```

---

## Update Team

```
PATCH /teams/:id
```

Update a team's title.

### Authentication

Requires `ApiKey` with `full` scope.

### Path Parameters

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `id`      | string | The team ID |

### Request Body

| Field   | Type   | Required | Description                     |
| ------- | ------ | -------- | ------------------------------- |
| `title` | string | ✅       | New team name. 1–36 characters. |

### Request

```bash
curl -X PATCH "https://{workspace_id}.firetell.app/api/v1/teams/te_a1b2c3d4e5f6a7b8c9d0e1f2" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Premium Support"
  }'
```

### Response

Returns the updated team object:

```json
{
  "id": "te_a1b2c3d4e5f6a7b8c9d0e1f2",
  "title": "Premium Support",
  "workspace_id": "yourcompany",
  "agent_count": 12,
  "created_at": "2026-01-10T09:00:00.000Z",
  "updated_at": "2026-07-09T09:30:00.000Z"
}
```

### Error Response

```json
{
  "statusCode": 400,
  "message": "Team not found or does not belong to this workspace",
  "error": "Bad Request"
}
```

---

## Delete Team

```
DELETE /teams/:id
```

Permanently delete a team. All agent memberships in this team will be automatically removed.

### Authentication

Requires `ApiKey` with `full` scope.

:::caution
This action is irreversible. All agents will be removed from the team, but the agent accounts themselves will not be affected.
:::

### Path Parameters

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `id`      | string | The team ID |

### Request

```bash
curl -X DELETE "https://{workspace_id}.firetell.app/api/v1/teams/te_a1b2c3d4e5f6a7b8c9d0e1f2" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

### Response

Returns the deleted team object:

```json
{
  "id": "te_a1b2c3d4e5f6a7b8c9d0e1f2",
  "title": "Support Team",
  "workspace_id": "yourcompany",
  "agent_count": 12,
  "created_at": "2026-01-10T09:00:00.000Z",
  "updated_at": "2026-03-20T14:00:00.000Z"
}
```

---

## List Team Agents

```
GET /teams/:id/agents
```

Retrieve a paginated list of agents that belong to a specific team, including their role and populated agent details.

### Authentication

Requires `ApiKey` with any scope.

### Path Parameters

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `id`      | string | The team ID |

### Query Parameters

| Parameter    | Type   | Default      | Description                 |
| ------------ | ------ | ------------ | --------------------------- |
| `page`       | number | `1`          | Page number                 |
| `limit`      | number | `10`         | Items per page (max: 100)   |
| `sort_field` | string | `created_at` | Sort field                  |
| `sort_order` | string | `desc`       | Sort order: `asc` or `desc` |

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/teams/te_a1b2c3d4e5f6a7b8c9d0e1f2/agents?page=1&limit=10" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

### Response

```json
{
  "data": [
    {
      "team_id": "te_a1b2c3d4e5f6a7b8c9d0e1f2",
      "agent_id": "ag_7f3a2b1c9d4e5f6a8b0c1d2e",
      "workspace_id": "yourcompany",
      "role": "leader",
      "agent": {
        "id": "ag_7f3a2b1c9d4e5f6a8b0c1d2e",
        "display_name": "John Doe",
        "avatar": "https://s3.amazonaws.com/bucket/yourcompany/avatars/abc123.webp",
        "email": "john@example.com",
        "username": "johndoe",
        "country_code": "US"
      },
      "created_at": "2026-02-01T10:00:00.000Z",
      "updated_at": "2026-02-01T10:00:00.000Z"
    },
    {
      "team_id": "te_a1b2c3d4e5f6a7b8c9d0e1f2",
      "agent_id": "ag_9a8b7c6d5e4f3a2b1c0d9e8f",
      "workspace_id": "yourcompany",
      "role": "member",
      "agent": {
        "id": "ag_9a8b7c6d5e4f3a2b1c0d9e8f",
        "display_name": "Jane Doe",
        "avatar": null,
        "email": "jane@example.com",
        "username": "janedoe",
        "country_code": "VN"
      },
      "created_at": "2026-02-05T14:30:00.000Z",
      "updated_at": "2026-02-05T14:30:00.000Z"
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}
```

---

## Add Agent to Team

```
PUT /teams/:id/agents/:agent_id
```

Add an agent to a team. If the agent is already in the team, their role will be updated. The team's `agent_count` is automatically recalculated.

### Authentication

Requires `ApiKey` with `full` scope.

### Path Parameters

| Parameter  | Type   | Description         |
| ---------- | ------ | ------------------- |
| `id`       | string | The team ID         |
| `agent_id` | string | The agent ID to add |

### Request

```bash
curl -X PUT "https://{workspace_id}.firetell.app/api/v1/teams/te_a1b2c3d4e5f6a7b8c9d0e1f2/agents/ag_7f3a2b1c9d4e5f6a8b0c1d2e" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

### Response

Returns the team-agent membership with populated agent details:

```json
{
  "team_id": "te_a1b2c3d4e5f6a7b8c9d0e1f2",
  "agent_id": "ag_7f3a2b1c9d4e5f6a8b0c1d2e",
  "workspace_id": "yourcompany",
  "role": "member",
  "agent": {
    "id": "ag_7f3a2b1c9d4e5f6a8b0c1d2e",
    "display_name": "John Doe",
    "avatar": null,
    "email": "john@example.com",
    "username": "johndoe",
    "country_code": "US"
  },
  "created_at": "2026-07-09T08:00:00.000Z",
  "updated_at": "2026-07-09T08:00:00.000Z"
}
```

:::tip
This endpoint uses **upsert** behavior — if the agent is already in the team, the request will succeed and update the membership rather than returning an error.
:::

### Error Response

```json
{
  "statusCode": 400,
  "message": "Agent not found or does not belong to this workspace",
  "error": "Bad Request"
}
```

---

## Remove Agent from Team

```
DELETE /teams/:id/agents/:agent_id
```

Remove an agent from a team. The team's `agent_count` is automatically recalculated. The agent account itself is not affected.

### Authentication

Requires `ApiKey` with `full` scope.

### Path Parameters

| Parameter  | Type   | Description            |
| ---------- | ------ | ---------------------- |
| `id`       | string | The team ID            |
| `agent_id` | string | The agent ID to remove |

### Request

```bash
curl -X DELETE "https://{workspace_id}.firetell.app/api/v1/teams/te_a1b2c3d4e5f6a7b8c9d0e1f2/agents/ag_7f3a2b1c9d4e5f6a8b0c1d2e" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

### Response

Returns the removed team-agent membership with populated agent details:

```json
{
  "team_id": "te_a1b2c3d4e5f6a7b8c9d0e1f2",
  "agent_id": "ag_7f3a2b1c9d4e5f6a8b0c1d2e",
  "workspace_id": "yourcompany",
  "role": "member",
  "agent": {
    "id": "ag_7f3a2b1c9d4e5f6a8b0c1d2e",
    "display_name": "John Doe",
    "avatar": null,
    "email": "john@example.com",
    "username": "johndoe",
    "country_code": "US"
  },
  "created_at": "2026-02-01T10:00:00.000Z",
  "updated_at": "2026-02-01T10:00:00.000Z"
}
```

---

## Suggest Agents

```
GET /teams/:id/suggestion-agents
```

Get a list of agents who are **not yet members** of the specified team. Useful for building "Add Agent" UI with search functionality.

### Authentication

Requires `ApiKey` with any scope.

### Path Parameters

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `id`      | string | The team ID |

### Query Parameters

| Parameter | Type   | Description                                      |
| --------- | ------ | ------------------------------------------------ |
| `search`  | string | Search by agent display name, email, or username |

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/teams/te_a1b2c3d4e5f6a7b8c9d0e1f2/suggestion-agents?search=john" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

### Response

Returns up to 20 agents not in the team:

```json
{
  "items": [
    {
      "id": "ag_d4e5f6a7b8c9d0e1f2a3b4c5",
      "username": "johnsmith",
      "domain": "yourcompany.firetell.app",
      "display_name": "John Smith",
      "email": "johnsmith@example.com",
      "avatar": null,
      "state": "available",
      "is_active": true,
      "workspace_id": "yourcompany",
      "country_code": "US",
      "created_at": "2026-03-01T08:00:00.000Z",
      "updated_at": "2026-03-01T08:00:00.000Z"
    }
  ]
}
```

:::info
This endpoint returns a maximum of **20 results** and does not support pagination. Use the `search` parameter to narrow down results.
:::

### Error Response

```json
{
  "statusCode": 404,
  "message": "Team not found or does not belong to this workspace",
  "error": "Not Found"
}
```