Returns one page sorted by team name and team ID. By default, the response excludes archived teams.

Operation ID

listTeams

Scope

teams:read

Prerequisites

None

Retry guidance

This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules

curl --request GET \
  --url 'https://{company}.api.tellagen.com/api/v1/teams' \
  --header 'Authorization: Bearer <token>'

{
  "teams": [
    {
      "id": 42,
      "revision": 2,
      "company_id": 7,
      "name": "Platform Team",
      "slug": "platform_team",
      "description": "Core platform infrastructure",
      "member_count": 12,
      "created_at": "2025-01-10T09:00:00Z",
      "updated_at": "2025-01-10T09:00:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": true,
    "next_cursor": "opaque-server-cursor"
  }
}

Creates a team. If slug is omitted, the API creates it from name. A parent team must be active. If any team already uses the slug, the API returns 409. This includes archived teams.

Operation ID

createTeam

Scope

teams:write

Prerequisites

Active responder seatManage teams

Retry guidance

Retry an identical request with the same Idempotency-Key used on the first attempt, within 24 hours. Never retry an unknown outcome automatically. Retry rules

curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/teams' \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Platform Team",
  "description": "Core platform infrastructure"
}'

{
  "team": {
    "id": 42,
    "revision": 1,
    "company_id": 7,
    "name": "Platform Team",
    "slug": "platform_team",
    "description": "Core platform infrastructure",
    "created_at": "2025-01-30T12:00:00Z",
    "updated_at": "2025-01-30T12:00:00Z"
  }
}

Returns one team by its positive numeric ID. A team remains available by ID after it is archived.

Operation ID

getTeam

Scope

teams:read

Prerequisites

None

Retry guidance

This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules

curl --request GET \
  --url 'https://{company}.api.tellagen.com/api/v1/teams/{id}' \
  --header 'Authorization: Bearer <token>'

{
  "team": {
    "id": 42,
    "revision": 2,
    "company_id": 7,
    "name": "Platform Team",
    "slug": "platform_team",
    "description": "Core platform infrastructure",
    "created_at": "2025-01-10T09:00:00Z",
    "updated_at": "2025-01-10T09:00:00Z"
  }
}

Updates an active team. If the request supplies a parent team, that team must be active. The update must not create a hierarchy cycle. Omitted fields stay unchanged.

Operation ID

updateTeam

Scope

teams:write

Prerequisites

Active responder seatManage teams

Retry guidance

Read the current resource and reconcile changes before retrying with its current version. A stale version returns 412. Retry rules

curl --request PATCH \
  --url 'https://{company}.api.tellagen.com/api/v1/teams/{id}' \
  --header 'Authorization: Bearer <token>' \
  --header 'If-Tellagen-Resource-Version: <resource-version>' \
  --header 'Content-Type: application/json' \
  --data '{
  "description": "Core platform and infrastructure"
}'

{
  "team": {
    "id": 42,
    "revision": 3,
    "company_id": 7,
    "name": "Platform Team",
    "slug": "platform_team",
    "description": "Core platform and infrastructure",
    "created_at": "2025-01-10T09:00:00Z",
    "updated_at": "2025-01-30T12:00:00Z"
  }
}

Archives a team. A repeated request returns 204 without changing the archive time or resource version. The API retains memberships and child-team relationships. The archived team remains available by ID. It cannot be updated.

Operation ID

archiveTeam

Scope

teams:write

Prerequisites

Active responder seatManage teams

Retry guidance

Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules

curl --request DELETE \
  --url 'https://{company}.api.tellagen.com/api/v1/teams/{id}' \
  --header 'Authorization: Bearer <token>'

Restores an archived team and returns the active team. A repeated request returns the active team without changing its resource version. If the team has parent_team_id, that parent team must be active. Otherwise, the API returns 409 invalid_relationship_state. The API retains team memberships.

Operation ID

restoreTeam

Scope

teams:write

Prerequisites

Active responder seatManage teams

Retry guidance

Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules

curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/teams/{id}/restore' \
  --header 'Authorization: Bearer <token>'

{
  "team": {
    "id": 42,
    "revision": 3,
    "company_id": 7,
    "name": "Platform Team",
    "slug": "platform_team",
    "description": "Core platform and infrastructure",
    "created_at": "2025-01-10T09:00:00Z",
    "updated_at": "2025-01-30T12:00:00Z"
  }
}

Returns one page sorted by membership creation time and user ID. Each entry includes membership and user details.

Operation ID

listTeamMembers

Scope

teams:read

Prerequisites

None

Retry guidance

This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules

curl --request GET \
  --url 'https://{company}.api.tellagen.com/api/v1/teams/{id}/members' \
  --header 'Authorization: Bearer <token>'

{
  "members": [
    {
      "team_id": 42,
      "user_id": 100,
      "role": "lead",
      "email": "[email protected]",
      "display_name": "Jane Doe",
      "avatar_url": ""
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": false
  }
}

Adds an active workspace member to an active team. If the team membership already exists, the API updates its role.

Operation ID

addTeamMember

Scope

teams:write

Prerequisites

Active responder seatManage teams

Retry guidance

Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules

curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/teams/{id}/members' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "user_id": 100,
  "role": "lead"
}'

{
  "member": {
    "team_id": 42,
    "user_id": 100,
    "role": "lead",
    "created_at": "2025-01-30T12:00:00Z"
  }
}

Updates the team role for an active workspace member. If the team membership does not exist, the API returns 404.

Operation ID

updateTeamMember

Scope

teams:write

Prerequisites

Active responder seatManage teams

Retry guidance

Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules

curl --request PATCH \
  --url 'https://{company}.api.tellagen.com/api/v1/teams/{id}/members/{userId}' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "role": "member"
}'

{
  "member": {
    "team_id": 42,
    "user_id": 100,
    "role": "member",
    "created_at": "2025-01-10T09:00:00Z"
  }
}

Removes one user from the team. The operation does not remove the user from the workspace.

Operation ID

removeTeamMember

Scope

teams:write

Prerequisites

Active responder seatManage teams

Retry guidance

Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules

curl --request DELETE \
  --url 'https://{company}.api.tellagen.com/api/v1/teams/{id}/members/{userId}' \
  --header 'Authorization: Bearer <token>'