Teams

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

Last updated 8 days ago

Was this helpful?

Create organization team

Creates a team in the specified organization.

put

/orgs/{organizationId}/teams

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Body

titlestringrequired

Title of the team

membersstring[]

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":[null]}'

201

default

{
  "title": "text",
  "id": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-02-15T11:46:07.260Z",
  "object": "team"
}

Team has been created

Get specified organization team

Gets a specific team in an organization.

get

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

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

default

{
  "title": "text",
  "id": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-02-15T11:46:07.260Z",
  "object": "team"
}

Update specified organization team

Updates a specific team in an organization.

patch

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

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

teamIdstringrequired

The unique ID of the Team

Body

titlestringrequired

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

default

{
  "title": "text",
  "id": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-02-15T11:46:07.260Z",
  "object": "team"
}

The team has been updated

Delete a team in an organization

Deletes a specific team in an organization

delete

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

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

204

default

No body

The team was deleted from the organization.

List team members

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

get

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

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

teamIdstringrequired

The unique ID of the Team

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber

The number of results per page

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "organization": {
        "role": "admin",
        "user": {
          "id": "text",
          "displayName": "text",
          "email": "text",
          "photoURL": "text",
          "object": "user",
          "urls": {
            "location": "https://example.com"
          }
        },
        "spaces": 1,
        "teams": 1,
        "id": "text",
        "disabled": true,
        "joinedAt": "2025-02-15T11:46:07.260Z",
        "lastSeenAt": "2025-02-15T11:46:07.260Z",
        "sso": true,
        "object": "member"
      },
      "team": {
        "role": "owner"
      }
    }
  ]
}

Updates members of an organization team

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.

put

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

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

teamIdstringrequired

The unique ID of the Team

Body

membershipsobject

addstring[]

removestring[]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}/members' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"memberships":{"ANY_ADDITIONAL_PROPERTY":{"role":"owner"}},"add":[null],"remove":[null]}'

204

default

No body

Members have been updated

Add or update a team membership

Add or updates member in the specified organization team.

put

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

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

teamIdstringrequired

The unique ID of the Team

userIdstringrequired

The unique ID of the User

Body

roleenum

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

Options: owner, member

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}/members/{userId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"role":"owner"}'

204

default

No body

Member has been added to the team

Delete members from a team

Deletes member from the specified organization team.

delete

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

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

teamIdstringrequired

The unique ID of the Team

userIdstringrequired

The unique ID of the User

Responses

application/json

cURL

JavaScript

Python

HTTP

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

204

default

No body

Member has been deleted from the team

List organization teams

Lists teams for the specified organization.

get

/orgs/{organizationId}/teams

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber

The number of results per page

ownerstring

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

titlestring

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

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "title": "text",
      "id": "text",
      "members": 1,
      "spaces": 1,
      "createdAt": "2025-02-15T11:46:07.260Z",
      "object": "team"
    }
  ]
}