API ReferenceTeams

Teams

Creates, lists, reads, updates, archives, and restores teams. This section also manages team memberships.

Search API docsAll documentation

Search all guides and API reference text. Method and scope filter endpoints only.

MethodScope

Endpoints

List teams

GET/api/v1/teams

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

Required scope: teams:read

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

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

Success: 200

Returns teams and pagination fields.

Success response JSON

json

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

Parameters, headers, and fields

Operation ID: listTeams

Query parameters

Query parameters
Field	Description
`limit` integer Optional	The maximum number of items in one page. The default is 50, and the maximum is 100. Minimum: 1. · Maximum: 100. · Default: 50.
`cursor` string Optional	The next_cursor value from the previous page. Clients treat this value as opaque and do not create, inspect, or change it. Minimum length: 1 characters. · Maximum length: 4096 characters.
`include_archived` boolean Optional	Controls whether the response includes archived teams. The default is false. Default: false.

Response `200`

Returns teams and pagination fields.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`teams` object[] Always returned	The teams in this page.
`teams[].id` integer Always returned	The positive numeric ID of the team. Minimum: 1.
`teams[].revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`teams[].company_id` integer Always returned	The ID of the workspace that owns the team. Minimum: 1.
`teams[].name` string Always returned	The display name of the team.
`teams[].slug` string Always returned	The permanent key used to identify the team.
`teams[].description` string Sometimes returned	The workspace description of the team.
`teams[].parent_team_id` integer Sometimes returned	The positive ID of the parent team. This field is absent for a root team. Minimum: 1.
`teams[].member_count` integer Sometimes returned	The number of active workspace members in the team. Minimum: 0.
`teams[].created_at` string (RFC 3339) Always returned	The team creation time.
`teams[].updated_at` string (RFC 3339) Always returned	The time of the latest team change.
`teams[].archived_at` string (RFC 3339) Sometimes returned	The team archive time. This field is absent for an active team.
`pagination` object Always returned	Pagination details for a collection response.
`pagination.limit` integer Always returned	The maximum number of items requested for this page. Minimum: 1. · Maximum: 100.
`pagination.has_more` boolean Always returned	Indicates whether another page is available.
`pagination.next_cursor` string Sometimes returned	The opaque cursor for the next page. This field is absent on the final page.

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Create team

POST/api/v1/teams

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.

Required scope: teams:write
Also required: Active responder seat Manage teams

Example request

Replace {company}, <token>, and any other placeholders with your values.

For <idempotency-key>, choose a unique key on the first attempt. Reuse it only when retrying the identical request.

bash

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"
}'

Success: 201

Returns the created team.

Success response JSON

json

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

Parameters, headers, and fields

Operation ID: createTeam

Request headers

Request headers
Field	Description
`Idempotency-Key` string Optional	A key for safe retries of a create request. It must contain 1–128 visible, non-space ASCII characters. The same key applies only to an identical request. Minimum length: 1 characters. · Maximum length: 128 characters. · Pattern: ^[\x21-\x7E]+$.

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	Description
`name` string Required	The team name. The length must be from 1 through 128 characters. Minimum length: 1 characters. · Maximum length: 128 characters.
`slug` string Optional	A permanent team key. It starts with a lowercase letter and contains lowercase letters, digits, or underscores. If slug is omitted, the API creates it from name.
`description` string Optional	The workspace description of the team.
`parent_team_id` integer Optional	The positive ID of an active parent team. If the request omits parent_team_id, the API creates a root team. Minimum: 1.

Response `201`

Returns the created team.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`team` object Always returned	The complete public record for a team.
`team.id` integer Always returned	The positive numeric ID of the team. Minimum: 1.
`team.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`team.company_id` integer Always returned	The ID of the workspace that owns the team. Minimum: 1.
`team.name` string Always returned	The display name of the team.
`team.slug` string Always returned	The permanent key used to identify the team.
`team.description` string Sometimes returned	The workspace description of the team.
`team.parent_team_id` integer Sometimes returned	The positive ID of the parent team. This field is absent for a root team. Minimum: 1.
`team.member_count` integer Sometimes returned	The number of active workspace members in the team. Minimum: 0.
`team.created_at` string (RFC 3339) Always returned	The team creation time.
`team.updated_at` string (RFC 3339) Always returned	The time of the latest team change.
`team.archived_at` string (RFC 3339) Sometimes returned	The team archive time. This field is absent for an active team.

Response headers

Response headers
Field	Description
`Tellagen-Resource-Version` integer Always returned	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (7)

Within 24 hours, retry with the original Idempotency-Key and identical body. If the result is unknown, do not retry automatically. Check whether the resource exists. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

idempotency_key_reused idempotency_in_progress idempotency_outcome_unknown

Get team

GET/api/v1/teams/{id}

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

Required scope: teams:read

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

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

Success: 200

Returns the team.

Success response JSON

json

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

Parameters, headers, and fields

Operation ID: getTeam

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric team ID returned by this API. Minimum: 1.

Response `200`

Returns the team.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`team` object Always returned	The complete public record for a team.
`team.id` integer Always returned	The positive numeric ID of the team. Minimum: 1.
`team.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`team.company_id` integer Always returned	The ID of the workspace that owns the team. Minimum: 1.
`team.name` string Always returned	The display name of the team.
`team.slug` string Always returned	The permanent key used to identify the team.
`team.description` string Sometimes returned	The workspace description of the team.
`team.parent_team_id` integer Sometimes returned	The positive ID of the parent team. This field is absent for a root team. Minimum: 1.
`team.member_count` integer Sometimes returned	The number of active workspace members in the team. Minimum: 0.
`team.created_at` string (RFC 3339) Always returned	The team creation time.
`team.updated_at` string (RFC 3339) Always returned	The time of the latest team change.
`team.archived_at` string (RFC 3339) Sometimes returned	The team archive time. This field is absent for an active team.

Response headers

Response headers
Field	Description
`Tellagen-Resource-Version` integer Always returned	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Update team

PATCH/api/v1/teams/{id}

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.

Required scope: teams:write
Also required: Active responder seat Manage teams

Example request

Replace {company}, <token>, and any other placeholders with your values.

Use the Tellagen-Resource-Version header from a GET of this resource for <resource-version>.

bash

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"
}'

Success: 200

Returns the updated team.

Success response JSON

json

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

Parameters, headers, and fields

Operation ID: updateTeam

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric team ID returned by this API. Minimum: 1.

Request headers

Request headers
Field	Description
`If-Tellagen-Resource-Version` integer Required	The current positive resource version from the latest response. API-key PATCH requests must send this value. Minimum: 1.

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	Description
`name` string Optional	The team name. The length must be from 1 through 128 characters. Minimum length: 1 characters. · Maximum length: 128 characters.
`description` string Optional	The replacement team description.
`parent_team_id` integer \| null Optional	The positive ID of an active parent team. A null value makes this team a root team.

Response `200`

Returns the updated team.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`team` object Always returned	The complete public record for a team.
`team.id` integer Always returned	The positive numeric ID of the team. Minimum: 1.
`team.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`team.company_id` integer Always returned	The ID of the workspace that owns the team. Minimum: 1.
`team.name` string Always returned	The display name of the team.
`team.slug` string Always returned	The permanent key used to identify the team.
`team.description` string Sometimes returned	The workspace description of the team.
`team.parent_team_id` integer Sometimes returned	The positive ID of the parent team. This field is absent for a root team. Minimum: 1.
`team.member_count` integer Sometimes returned	The number of active workspace members in the team. Minimum: 0.
`team.created_at` string (RFC 3339) Always returned	The team creation time.
`team.updated_at` string (RFC 3339) Always returned	The time of the latest team change.
`team.archived_at` string (RFC 3339) Sometimes returned	The team archive time. This field is absent for an active team.

Response headers

Response headers
Field	Description
`Tellagen-Resource-Version` integer Always returned	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (9)

If the API returns 412, read the resource again. Compare the latest changes before you retry with the new version. Retries and updates

Error responses (9)

400 401 403 404 409 412 428 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
412: The resource changed after the client obtained its If-Tellagen-Resource-Version value.
428: An API-key PATCH request did not include the required If-Tellagen-Resource-Version header.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Archive team

DELETE/api/v1/teams/{id}

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.

Required scope: teams:write
Also required: Active responder seat Manage teams

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

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

Success: 204

No response body. Do not try to parse this response as JSON.

Parameters, headers, and fields

Operation ID: archiveTeam

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric team ID returned by this API. Minimum: 1.

Returns 204 with no body.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Restore team

POST/api/v1/teams/{id}/restore

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.

Required scope: teams:write
Also required: Active responder seat Manage teams

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

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

Success: 200

Returns the complete active team.

Success response JSON

json

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

Parameters, headers, and fields

Operation ID: restoreTeam

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric team ID returned by this API. Minimum: 1.

Response `200`

Returns the complete active team.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`team` object Always returned	The complete public record for a team.
`team.id` integer Always returned	The positive numeric ID of the team. Minimum: 1.
`team.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`team.company_id` integer Always returned	The ID of the workspace that owns the team. Minimum: 1.
`team.name` string Always returned	The display name of the team.
`team.slug` string Always returned	The permanent key used to identify the team.
`team.description` string Sometimes returned	The workspace description of the team.
`team.parent_team_id` integer Sometimes returned	The positive ID of the parent team. This field is absent for a root team. Minimum: 1.
`team.member_count` integer Sometimes returned	The number of active workspace members in the team. Minimum: 0.
`team.created_at` string (RFC 3339) Always returned	The team creation time.
`team.updated_at` string (RFC 3339) Always returned	The time of the latest team change.
`team.archived_at` string (RFC 3339) Sometimes returned	The team archive time. This field is absent for an active team.

Response headers

Response headers
Field	Description
`Tellagen-Resource-Version` integer Always returned	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

invalid_relationship_state

List team members

GET/api/v1/teams/{id}/members

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

Required scope: teams:read

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

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

Success: 200

Returns team members and pagination fields.

Success response JSON

json

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

Parameters, headers, and fields

Operation ID: listTeamMembers

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric team ID returned by this API. Minimum: 1.

Query parameters

Query parameters
Field	Description
`limit` integer Optional	The maximum number of items in one page. The default is 50, and the maximum is 100. Minimum: 1. · Maximum: 100. · Default: 50.
`cursor` string Optional	The next_cursor value from the previous page. Clients treat this value as opaque and do not create, inspect, or change it. Minimum length: 1 characters. · Maximum length: 4096 characters.

Response `200`

Returns team members and pagination fields.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`members` object[] Always returned	The team memberships in this page.
`members[].team_id` integer Always returned	The positive numeric ID of the team.
`members[].user_id` integer Always returned	The positive numeric ID of the workspace member.
`members[].role` string Always returned	The role in this team. Possible values: `"lead""member"`
`members[].email` string Always returned	The email address of the workspace member.
`members[].display_name` string Sometimes returned	The display name of the workspace member.
`members[].avatar_url` string Sometimes returned	The avatar URL of the workspace member.
`pagination` object Always returned	Pagination details for a collection response.
`pagination.limit` integer Always returned	The maximum number of items requested for this page. Minimum: 1. · Maximum: 100.
`pagination.has_more` boolean Always returned	Indicates whether another page is available.
`pagination.next_cursor` string Sometimes returned	The opaque cursor for the next page. This field is absent on the final page.

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Add team member

POST/api/v1/teams/{id}/members

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

Required scope: teams:write
Also required: Active responder seat Manage teams

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

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"
}'

Success: 201

Returns the created or updated team membership.

Success response JSON

json

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

Parameters, headers, and fields

Operation ID: addTeamMember

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric team ID returned by this API. Minimum: 1.

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	Description
`user_id` integer Required	The positive ID of the active workspace member to add. Minimum: 1.
`role` string Optional	The role in this team. If the request omits role, the API uses member. Default: "member". Allowed values: `"lead""member"`

Response `201`

Returns the created or updated team membership.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`member` object Always returned	The team membership returned after a create or update request.
`member.team_id` integer Always returned	The positive numeric ID of the team. Minimum: 1.
`member.user_id` integer Always returned	The positive numeric ID of the workspace member. Minimum: 1.
`member.role` string Always returned	The role in this team. Possible values: `"lead""member"`
`member.created_at` string (RFC 3339) Always returned	The membership creation time.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Update team member

PATCH/api/v1/teams/{id}/members/{userId}

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

Required scope: teams:write
Also required: Active responder seat Manage teams

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

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"
}'

Success: 200

Returns the updated team membership.

Success response JSON

json

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

Parameters, headers, and fields

Operation ID: updateTeamMember

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric team ID returned by this API. Minimum: 1.
`userId` integer Required	A positive numeric user ID for an active workspace member. Minimum: 1.

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	Description
`role` string Required	The new team role. Allowed values: `"lead""member"`

Response `200`

Returns the updated team membership.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`member` object Always returned	The team membership returned after a create or update request.
`member.team_id` integer Always returned	The positive numeric ID of the team. Minimum: 1.
`member.user_id` integer Always returned	The positive numeric ID of the workspace member. Minimum: 1.
`member.role` string Always returned	The role in this team. Possible values: `"lead""member"`
`member.created_at` string (RFC 3339) Always returned	The membership creation time.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Remove team member

DELETE/api/v1/teams/{id}/members/{userId}

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

Required scope: teams:write
Also required: Active responder seat Manage teams

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

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

Success: 204

No response body. Do not try to parse this response as JSON.

Parameters, headers, and fields

Operation ID: removeTeamMember

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric team ID returned by this API. Minimum: 1.
`userId` integer Required	A positive numeric user ID for an active workspace member. Minimum: 1.

Returns 204 with no body.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Read this resource as Markdown · OpenAPI specification

Teams

Endpoints

List teams

Example request

Success: 200

Query parameters

Response 200

Error responses (7)

Create team

Example request

Success: 201

Request headers

Request body

Response 201

Response headers

Error responses (7)

Get team

Example request

Success: 200

Path parameters

Response 200

Response headers

Error responses (7)

Update team

Example request

Success: 200

Path parameters

Request headers

Request body

Response 200

Response headers

Error responses (9)

Archive team

Example request

Success: 204

Path parameters

Error responses (7)

Restore team

Example request

Success: 200

Path parameters

Response 200

Response headers

Error responses (7)

List team members

Example request

Success: 200

Path parameters

Query parameters

Response 200

Error responses (7)

Add team member

Example request

Success: 201

Path parameters

Request body

Response 201

Error responses (7)

Update team member

Example request

Success: 200

Path parameters

Request body

Response 200

Error responses (7)

Remove team member

Example request

Success: 204

Path parameters

Error responses (7)

Response `200`

Response `201`

Response `200`

Response `200`

Response `200`

Response `200`

Response `201`

Response `200`