Teams

A team in GitBook is the entity of a group that members of an organization belong to.

List all teams

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

200

OK

application/json

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": "2025-12-27T04:10:03.689Z",
      "permissions": {
        "admin": true,
        "view": true
      }
    }
  ]
}

Create a team

put

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

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": "2025-12-27T04:10:03.689Z",
  "permissions": {
    "admin": true,
    "view": true
  }
}

Get a team

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

teamIdstringRequired

The unique ID of the Team

Responses

200

OK

application/json

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": "2025-12-27T04:10:03.689Z",
  "permissions": {
    "admin": true,
    "view": true
  }
}

Update a team

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

teamIdstringRequired

The unique ID of the Team

Body

application/json

titlestring · min: 1 · max: 64Required

Title of the team

Responses

200

The team has been updated

application/json

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": "2025-12-27T04:10:03.689Z",
  "permissions": {
    "admin": true,
    "view": true
  }
}

Delete a team

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

teamIdstringRequired

The unique ID of the Team

Responses

204

The team did not exist in the organization.

No content

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

List all team members

get

Lists members, and their roles, for the specified organization team.

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

teamIdstringRequired

The unique ID of the Team

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

OK

application/json

get

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

HTTPcURLJavaScriptPython

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

200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "organization": {
        "object": "member",
        "id": "text",
        "role": "admin",
        "user": {
          "object": "user",
          "id": "text",
          "displayName": "text",
          "email": "text",
          "photoURL": "text",
          "urls": {
            "location": "https://example.com"
          }
        },
        "disabled": true,
        "joinedAt": "2025-12-27T04:10:03.689Z",
        "lastSeenAt": "2025-12-27T04:10:03.689Z",
        "sso": true,
        "spaces": 1,
        "teams": 1
      },
      "team": {
        "role": "owner"
      },
      "permissions": {
        "view": true
      }
    }
  ]
}

Updates members of a team

put

Updates members of an organization team, either adding or removing them. If a the same user is included as both an add and a remove, they will be removed from the team.

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

teamIdstringRequired

The unique ID of the Team

Body

application/json

addstring[]Optional

A user to add. It can either be a user ID or an email.

removestring[]Optional

A user to remove. It can either be a user ID or an email.

Responses

204

Members have been updated

No content

put

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

HTTPcURLJavaScriptPython

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

{
  "add": [
    "text"
  ],
  "memberships": {
    "ANY_ADDITIONAL_PROPERTY": {
      "role": "owner"
    }
  },
  "remove": [
    "text"
  ]
}

204

Members have been updated

No content

Add a team member

put

Add or updates member in the specified organization team.

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

teamIdstringRequired

The unique ID of the Team

userIdstringRequired

The unique ID of the User

Body

application/json

rolestring · enumOptional

"The role of a team member. "owner": Can manage team members. "member": Is a member of the team.

Possible values:

Responses

204

Member has been added to the team

No content

put

/orgs/{organizationId}/teams/{teamId}/members/{userId}

HTTPcURLJavaScriptPython

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

{
  "role": "owner"
}

204

Member has been added to the team

No content

Delete a team member

delete

Deletes member from the specified organization team.

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

teamIdstringRequired

The unique ID of the Team

userIdstringRequired

The unique ID of the User

Responses

204

Member was not part of the team

No content

205

Member has been deleted from the team

delete

/orgs/{organizationId}/teams/{teamId}/members/{userId}

HTTPcURLJavaScriptPython

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

No content