Teams

Create and manage teams as reusable groups of users.

Teams offer a convenient way to assign roles and access to multiple users at once. This helps maintain large-scale projects more efficiently by reducing overhead in user-by-user management.

The Team object

Attributes

objectstring · enumrequired

Type of Object, always equals to "team"

Available options:

idstringrequired

Unique identifier for the team

The Team object

{
  "object": "team",
  "id": "text"
}

List all teams

get

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Query parameters

pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

ownerstringoptional

The unique identifier of a member of the organization. Only teams they can manage will be returned.

titlestringoptional

If provided, only teams whose name contains the given parameter will be returned. Case insensitive.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/teams' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

200

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "team",
      "id": "text",
      "title": "text",
      "members": 1,
      "spaces": 1,
      "createdAt": "2025-04-16T19:34:42.780Z"
    }
  ]
}

OK

Create a team

put

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Body

titlestring · min: 1 · max: 64required

Title of the team

membersstring[]optional

A list of organization member identifiers

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/teams' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "members": [
      "text"
    ]
  }'

201

201

{
  "object": "team",
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-04-16T19:34:42.780Z"
}

Team has been created

Get a team

get

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

teamIdstringrequired

The unique ID of the Team

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

200

{
  "object": "team",
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-04-16T19:34:42.780Z"
}

OK

Delete a team

delete

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

teamIdstringrequired

The unique ID of the Team

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

204

204

No Content

The team was deleted from the organization.

Update a team

patch

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

teamIdstringrequired

The unique ID of the Team

Body

titlestring · min: 1 · max: 64required

Title of the team

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text"
  }'

200

200

{
  "object": "team",
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-04-16T19:34:42.780Z"
}

The team has been updated