Teams

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

GET teams in an organization

List organization teams

Lists teams for the specified organization.

GEThttps://api.gitbook.com/v1/orgs/{organizationId}/teams

Authorization

user

Path parameters

organizationId*string

The unique id of the organization

Query parameters

Response

200default

OK

Body

application/json

nextobject

countnumber

Total count of objects in the list

items*array of OrganizationTeam (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/orgs/{organizationId}/teams', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200default

{
  "next": {
    "page": "text"
  },
  "count": 0,
  "items": [
    {
      "object": "team",
      "id": "text",
      "title": "text",
      "spaces": 0,
      "createdAt": "2024-11-21T07:42:07.338Z"
    }
  ]
}

PUT a team in an organization

Create organization team

Creates a team in the specified organization.

PUThttps://api.gitbook.com/v1/orgs/{organizationId}/teams

Authorization

user

Path parameters

organizationId*string

The unique id of the organization

Body

application/json

title*OrganizationTeamTitle (string)

Title of the team

membersarray of string

A list of organization member identifiers

Response

201default

Team has been created

Body

application/json

object*enum

Type of Object, always equals to "team"

team

id*string

Unique identifier for the team.

title*OrganizationTeamTitle (string)

Title of the team

members*integer

Count of members in this team.

spaces*number

Count of spaces this team has access to.

createdAt*Timestamp (string (date-time))

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/orgs/{organizationId}/teams', {
    method: 'PUT',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "title": "text"
    }),
});
const data = await response.json();

Response

201default

{
  "object": "team",
  "id": "text",
  "title": "text",
  "spaces": 0,
  "createdAt": "2024-11-21T07:42:07.338Z"
}

GET a specific team in an organization

Get specified organization team

Gets a specific team in an organization.

GEThttps://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}

Authorization

user

Path parameters

organizationId*string

The unique id of the organization

teamId*string

The unique ID of the Team

Response

200default

OK

Body

application/json

object*enum

Type of Object, always equals to "team"

team

id*string

Unique identifier for the team.

title*OrganizationTeamTitle (string)

Title of the team

members*integer

Count of members in this team.

spaces*number

Count of spaces this team has access to.

createdAt*Timestamp (string (date-time))

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200default

{
  "object": "team",
  "id": "text",
  "title": "text",
  "spaces": 0,
  "createdAt": "2024-11-21T07:42:07.338Z"
}

PATCH a specific team in an organization

Update specified organization team

Updates a specific team in an organization.

PATCHhttps://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}

Authorization

user

Path parameters

organizationId*string

The unique id of the organization

teamId*string

The unique ID of the Team

Body

application/json

title*OrganizationTeamTitle (string)

Title of the team

Response

200default

The team has been updated

Body

application/json

object*enum

Type of Object, always equals to "team"

team

id*string

Unique identifier for the team.

title*OrganizationTeamTitle (string)

Title of the team

members*integer

Count of members in this team.

spaces*number

Count of spaces this team has access to.

createdAt*Timestamp (string (date-time))

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "title": "text"
    }),
});
const data = await response.json();

Response

200default

{
  "object": "team",
  "id": "text",
  "title": "text",
  "spaces": 0,
  "createdAt": "2024-11-21T07:42:07.338Z"
}

DELETE a specific team in an organization

Delete a team in an organization

Deletes a specific team in an organization

DELETEhttps://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}

Authorization

user

Path parameters

organizationId*string

The unique id of the organization

teamId*string

The unique ID of the Team

Response

204default

The team was deleted from the organization.

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

default

{
  "error": {
    "message": "text"
  }
}

GET team members in an organization

List team members

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

GEThttps://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}/members

Authorization

user

Path parameters

organizationId*string

The unique id of the organization

teamId*string

The unique ID of the Team

Query parameters

Response

200default

OK

Body

application/json

nextobject

countnumber

Total count of objects in the list

items*array of OrganizationTeamMember (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}/members', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200default

{
  "next": {
    "page": "text"
  },
  "count": 0,
  "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": false,
        "joinedAt": "2024-11-21T07:42:07.338Z",
        "lastSeenAt": "2024-11-21T07:42:07.338Z",
        "sso": false,
        "spaces": 0,
        "teams": 0
      },
      "team": {
        "role": "owner"
      }
    }
  ]
}

PUT team members in an organization

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.

PUThttps://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}/members

Authorization

user

Path parameters

organizationId*string

The unique id of the organization

teamId*string

The unique ID of the Team

Body

application/json

addarray of string

membershipsobject

removearray of string

Response

204default

Members have been updated

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}/members', {
    method: 'PUT',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

default

{
  "error": {
    "message": "text"
  }
}

PUT a specific team member in an organization

Add or update a team membership

Add or updates member in the specified organization team.

PUThttps://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}/members/{userId}

Authorization

user

Path parameters

organizationId*string

The unique id of the organization

teamId*string

The unique ID of the Team

userId*string

The unique ID of the User

Body

application/json

roleTeamMemberRole (enum)

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

ownermember

Response

204default

Member has been added to the team

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}/members/{userId}', {
    method: 'PUT',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

default

{
  "error": {
    "message": "text"
  }
}

DELETE a specific team member in an organization

Delete members from a team

Deletes member from the specified organization team.

DELETEhttps://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}/members/{userId}

Authorization

user

Path parameters

organizationId*string

The unique id of the organization

teamId*string

The unique ID of the Team

userId*string

The unique ID of the User

Response

204default

Member has been deleted from the team

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}/members/{userId}', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

default

{
  "error": {
    "message": "text"
  }
}