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"

Possible values:

idstringRequired

Unique identifier for the team

The Team object

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

List all teams

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

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

200

OK

application/json

countnumberOptional

Total count of objects in the list

get

/orgs/{organizationId}/teams

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/teams HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "team",
      "id": "text",
      "title": "text",
      "members": 1,
      "spaces": 1,
      "createdAt": "2026-06-18T21:44:14.814Z",
      "permissions": {
        "admin": true,
        "view": true
      }
    }
  ]
}

Create a team

put

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

Body

application/json

titlestring · min: 1 · max: 64Required

Title of the team

membersstring[]Optional

A list of organization member identifiers

Responses

201

Team has been created

application/json

put

/orgs/{organizationId}/teams

HTTPcURLJavaScriptPython

PUT /v1/orgs/{organizationId}/teams HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 35

{
  "title": "text",
  "members": [
    "text"
  ]
}

201

Team has been created

{
  "object": "team",
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2026-06-18T21:44:14.814Z",
  "permissions": {
    "admin": true,
    "view": true
  }
}

Get a team

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

teamIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

Responses

200

OK

application/json

objectstring · enumRequired

Type of Object, always equals to "team"

Possible values:

idstringRequired

Unique identifier for the team.

titlestring · min: 1 · max: 64Required

Title of the team

membersintegerRequired

Count of members in this team.

spacesnumberRequired

Count of spaces this team has access to.

createdAtstring · date-timeRequired

Date at which the team was created.

get

/orgs/{organizationId}/teams/{teamId}

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/teams/{teamId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "object": "team",
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2026-06-18T21:44:14.814Z",
  "permissions": {
    "admin": true,
    "view": true
  }
}

Delete a team

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

teamIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

Responses

204

The team did not exist in the organization.

205

The team was deleted from the organization.

delete

/orgs/{organizationId}/teams/{teamId}

HTTPcURLJavaScriptPython

DELETE /v1/orgs/{organizationId}/teams/{teamId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a team

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

teamIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

Body

application/json

titlestring · min: 1 · max: 64Required

Title of the team

Responses

200

The team has been updated

application/json

objectstring · enumRequired

Type of Object, always equals to "team"

Possible values:

idstringRequired

Unique identifier for the team.

titlestring · min: 1 · max: 64Required

Title of the team

membersintegerRequired

Count of members in this team.

spacesnumberRequired

Count of spaces this team has access to.

createdAtstring · date-timeRequired

Date at which the team was created.

patch

/orgs/{organizationId}/teams/{teamId}

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/teams/{teamId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "title": "text"
}

200

The team has been updated

{
  "object": "team",
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2026-06-18T21:44:14.814Z",
  "permissions": {
    "admin": true,
    "view": true
  }
}