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

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

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

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

Response

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

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

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

{
  "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:

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

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:

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

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

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:

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

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

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

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:

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

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

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:

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

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:

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

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

Endpoints​

The Team Object​

Team Agent Object​

List Teams​

Authentication​

Query Parameters​

Request​

Response​

Get Team​

Authentication​

Path Parameters​

Request​

Response​

Error Response​

Create Team​

Authentication​

Request Body​

Request​

Response​

Error Response​

Update Team​

Authentication​

Path Parameters​

Request Body​

Request​

Response​

Error Response​

Delete Team​

Authentication​

Path Parameters​

Request​

Response​

List Team Agents​

Authentication​

Path Parameters​

Query Parameters​

Request​

Response​

Add Agent to Team​

Authentication​

Path Parameters​

Request​

Response​

Error Response​

Remove Agent from Team​

Authentication​

Path Parameters​

Request​

Response​

Suggest Agents​

Authentication​

Path Parameters​

Query Parameters​

Request​

Response​

Error Response​

Endpoints

The Team Object

Team Agent Object

List Teams

Authentication

Query Parameters

Request

Response

Get Team

Authentication

Path Parameters

Request

Response

Error Response

Create Team

Authentication

Request Body

Request

Response

Error Response

Update Team

Authentication

Path Parameters

Request Body

Request

Response

Error Response

Delete Team

Authentication

Path Parameters

Request

Response

List Team Agents

Authentication

Path Parameters

Query Parameters

Request

Response

Add Agent to Team

Authentication

Path Parameters

Request

Response

Error Response

Remove Agent from Team

Authentication

Path Parameters

Request

Response

Suggest Agents

Authentication

Path Parameters

Query Parameters

Request

Response

Error Response