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.

objectstring · enumrequired

Type of Object, always equals to "team"

Options: team

idstringrequired

Unique identifier for the team

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 -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/teams' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "team",
      "id": "text",
      "title": "text",
      "members": 1,
      "spaces": 1,
      "createdAt": "2025-04-18T22:59:05.324Z"
    }
  ]
}

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

{
  "object": "team",
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-04-18T22:59:05.324Z"
}

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 -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

{
  "object": "team",
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-04-18T22:59:05.324Z"
}

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 -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

204

No body

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

{
  "object": "team",
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-04-18T22:59:05.324Z"
}

The team has been updated

Was this helpful?