Organizations

Manage organizations and group users, spaces, and collections.

Was this helpful?

Set a user as an SSO member of an organization

post

/orgs/{organizationId}/members/{userId}/sso

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

userIdstringrequired

The unique ID of the User

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

default

{
  "id": "text",
  "role": "admin",
  "user": {
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "object": "user",
    "urls": {
      "location": "https://example.com"
    }
  },
  "disabled": true,
  "joinedAt": "2025-03-09T02:41:13.248Z",
  "lastSeenAt": "2025-03-09T02:41:13.248Z",
  "sso": true,
  "spaces": 1,
  "teams": 1,
  "object": "member"
}

The user has been added as an SSO member of the organization.

Use an invite to join an organization.

post

/orgs/{organizationId}/invites/{inviteId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

inviteIdstringrequired

The unique id of the invite

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/invites/{inviteId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{}

Get a custom field by its name

get

/orgs/{organizationId}/custom-fields/{fieldName}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

fieldNamestringrequired

The name of the custom field

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/custom-fields/{fieldName}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

default

{
  "id": "text",
  "name": "text",
  "title": "text",
  "description": "text",
  "type": "text",
  "placeholder": "text",
  "options": [
    "text"
  ],
  "createdAt": "2025-03-09T02:41:13.248Z",
  "updatedAt": "2025-03-09T02:41:13.248Z",
  "urls": {
    "location": "https://example.com"
  }
}

Delete a custom field in an organization

delete

/orgs/{organizationId}/custom-fields/{fieldName}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

fieldNamestringrequired

The name of the custom field

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/custom-fields/{fieldName}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

204

default

No body

Custom field has been deleted

Update a custom field in an organization

patch

/orgs/{organizationId}/custom-fields/{fieldName}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

fieldNamestringrequired

The name of the custom field

Body

titlestring · max: 100

descriptionstring · max: 200

placeholderstring · max: 100

optionsstring[]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/custom-fields/{fieldName}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "description": "text",
    "placeholder": "text",
    "options": [
      "text"
    ]
  }'

200

default

{
  "id": "text",
  "name": "text",
  "title": "text",
  "description": "text",
  "type": "text",
  "placeholder": "text",
  "options": [
    "text"
  ],
  "createdAt": "2025-03-09T02:41:13.248Z",
  "updatedAt": "2025-03-09T02:41:13.248Z",
  "urls": {
    "location": "https://example.com"
  }
}

Get a SAML provider in an organization by its ID

get

/orgs/{organizationId}/saml/{samlProviderId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

samlProviderIdstringrequired

The unique id of the SAML provider

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

404

default

{
  "id": "text",
  "label": "text",
  "ssoURL": "https://example.com",
  "entityID": "text",
  "certificate": "text",
  "defaultTeam": {
    "id": "text",
    "title": "text",
    "members": 1,
    "spaces": 1,
    "createdAt": "2025-03-09T02:41:13.248Z",
    "object": "team"
  },
  "defaultRole": "admin",
  "createdAt": "2025-03-09T02:41:13.248Z",
  "object": "saml-provider",
  "service": {
    "acsURL": "https://example.com",
    "startURL": "https://example.com",
    "entityID": "text"
  },
  "urls": {
    "location": "https://example.com"
  }
}

Delete a SAML provider in an organization

delete

/orgs/{organizationId}/saml/{samlProviderId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

samlProviderIdstringrequired

The unique id of the SAML provider

Responses

application/json

cURL

JavaScript

Python

HTTP

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

204

default

No body

SAML provider has been deleted

Update a SAML provider in an organization

patch

/orgs/{organizationId}/saml/{samlProviderId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

samlProviderIdstringrequired

The unique id of the SAML provider

Body

labelstring · min: 1 · max: 30

entityIDstring · max: 1024

certificatestring · max: 10000

ssoURLstring · uri · max: 2048

defaultTeamstring

defaultRoleone of

The role of a member in an organization, null for guests

"The role of a member in an organization. "admin": Can administrate the content: create, delete spaces, ... "create": Can create content. "review": Can review content. "edit": Can edit the content (live or change requests). "comment": Can access the content and its discussions. "read": Can access the content, but cannot update it in any way.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/saml/{samlProviderId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "label": "text",
    "entityID": "text",
    "certificate": "text",
    "ssoURL": "https://example.com",
    "defaultTeam": "text",
    "defaultRole": "admin"
  }'

200

default

{
  "id": "text",
  "label": "text",
  "ssoURL": "https://example.com",
  "entityID": "text",
  "certificate": "text",
  "defaultTeam": {
    "id": "text",
    "title": "text",
    "members": 1,
    "spaces": 1,
    "createdAt": "2025-03-09T02:41:13.248Z",
    "object": "team"
  },
  "defaultRole": "admin",
  "createdAt": "2025-03-09T02:41:13.248Z",
  "object": "saml-provider",
  "service": {
    "acsURL": "https://example.com",
    "startURL": "https://example.com",
    "entityID": "text"
  },
  "urls": {
    "location": "https://example.com"
  }
}

SAML provider has been updated

Deletes an organization invite.

delete

/orgs/{organizationId}/link-invites/{inviteId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

inviteIdstringrequired

The unique id of the invite

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/link-invites/{inviteId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

205

default

No body

The organization invite has been deleted

Update an organization invite.

patch

/orgs/{organizationId}/link-invites/{inviteId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

inviteIdstringrequired

The unique id of the invite

Body

one of

Update role of an organization invite

Update level of an organization content invite

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/link-invites/{inviteId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "role": "admin"
  }'

200

default

{
  "id": "text",
  "role": "admin",
  "object": "invite"
}

The organization invite has been updated

Get an organization by its ID

get

/orgs/{organizationId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

404

default

{
  "id": "text",
  "title": "text",
  "createdAt": "2025-03-09T02:41:13.248Z",
  "emailDomains": [
    "text"
  ],
  "hostname": "text",
  "type": "business",
  "useCase": "internalDocs",
  "communityType": "nonProfit",
  "defaultRole": "admin",
  "defaultContent": {
    "site": "text",
    "type": "site"
  },
  "sso": true,
  "ai": true,
  "inviteLinks": true,
  "plan": "free_2024",
  "customHostname": "text",
  "internal_isOnNewTrial": true,
  "object": "organization",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "blocked": {
    "reason": "security"
  },
  "internal_billingMigration": {
    "deadline": "2025-03-09T02:41:13.248Z",
    "discountPercent": 1,
    "discountEndDate": "2025-03-09T02:41:13.248Z"
  },
  "permissions": {
    "admin": true,
    "createContent": true
  },
  "trial": {
    "status": "notapplicable",
    "endDate": "2025-03-09T02:41:13.248Z",
    "decision": "downgrade"
  }
}

Update an organization by its ID

patch

/orgs/{organizationId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Body

titlestring · min: 2 · max: 255

Name of the organization

emailDomainsstring[]

hostnamestring · min: 3 · max: 32

Default hostname for the organization's public content, e.g. <org-hostname>.gitbook.io

defaultRoleone of

The role of a member in an organization, null for guests

ssoboolean

aiboolean

inviteLinksboolean

defaultContentone of

logoone of

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "emailDomains": [
      "text"
    ],
    "hostname": "text",
    "defaultRole": "admin",
    "sso": true,
    "ai": true,
    "inviteLinks": true,
    "defaultContent": {
      "site": "text",
      "type": "site"
    },
    "logo": "https://example.com"
  }'

200

400

default

{
  "id": "text",
  "title": "text",
  "createdAt": "2025-03-09T02:41:13.248Z",
  "emailDomains": [
    "text"
  ],
  "hostname": "text",
  "type": "business",
  "useCase": "internalDocs",
  "communityType": "nonProfit",
  "defaultRole": "admin",
  "defaultContent": {
    "site": "text",
    "type": "site"
  },
  "sso": true,
  "ai": true,
  "inviteLinks": true,
  "plan": "free_2024",
  "customHostname": "text",
  "internal_isOnNewTrial": true,
  "object": "organization",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "blocked": {
    "reason": "security"
  },
  "internal_billingMigration": {
    "deadline": "2025-03-09T02:41:13.248Z",
    "discountPercent": 1,
    "discountEndDate": "2025-03-09T02:41:13.248Z"
  },
  "permissions": {
    "admin": true,
    "createContent": true
  },
  "trial": {
    "status": "notapplicable",
    "endDate": "2025-03-09T02:41:13.248Z",
    "decision": "downgrade"
  }
}

The organization has been updated

Invite users to a given organization based on a list of emails

post

/orgs/{organizationId}/invites

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Body

roleone of

Default role to set on newly invited members.

ssoboolean

If true, invites the user as an SSO user of the organization. Defaults to false.

emailsone of[]required

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/invites' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "role": "admin",
    "sso": true,
    "emails": [
      "text"
    ]
  }'

200

400

default

{
  "invited": 1,
  "users": [
    "text"
  ],
  "failedSSOEmails": [
    "text"
  ]
}

Get the list of organizations for the currently authenticated user

get

/orgs

Authorizations

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/orgs' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "title": "text",
      "createdAt": "2025-03-09T02:41:13.248Z",
      "emailDomains": [
        "text"
      ],
      "hostname": "text",
      "type": "business",
      "useCase": "internalDocs",
      "communityType": "nonProfit",
      "defaultRole": "admin",
      "defaultContent": {
        "site": "text",
        "type": "site"
      },
      "sso": true,
      "ai": true,
      "inviteLinks": true,
      "plan": "free_2024",
      "customHostname": "text",
      "internal_isOnNewTrial": true,
      "object": "organization",
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "logo": "https://example.com"
      },
      "blocked": {
        "reason": "security"
      },
      "internal_billingMigration": {
        "deadline": "2025-03-09T02:41:13.248Z",
        "discountPercent": 1,
        "discountEndDate": "2025-03-09T02:41:13.248Z"
      },
      "permissions": {
        "admin": true,
        "createContent": true
      },
      "trial": {
        "status": "notapplicable",
        "endDate": "2025-03-09T02:41:13.248Z",
        "decision": "downgrade"
      }
    }
  ]
}

List invite links to an organization

get

/orgs/{organizationId}/link-invites

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "role": "admin",
      "object": "invite"
    }
  ]
}

List of invite links in the organization.

Create a new organization invite

post

/orgs/{organizationId}/link-invites

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Body

one of

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/link-invites' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "role": "admin"
  }'

201

default

{
  "id": "text",
  "role": "admin",
  "object": "invite"
}

The organization invite has been created

Search content in an organization

get

/orgs/{organizationId}/search

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Query parameters

querystring · max: 512required

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/search?query=text' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "title": "text",
      "pages": [
        {
          "id": "text",
          "title": "text",
          "path": "text",
          "sections": [
            {
              "id": "text",
              "title": "text",
              "path": "text",
              "body": "text",
              "urls": {
                "app": "https://example.com"
              }
            }
          ],
          "urls": {
            "app": "https://example.com"
          }
        }
      ]
    }
  ]
}

Get the custom fields for spaces in an organization

get

/orgs/{organizationId}/custom-fields

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "name": "text",
      "title": "text",
      "description": "text",
      "type": "text",
      "placeholder": "text",
      "options": [
        "text"
      ],
      "createdAt": "2025-03-09T02:41:13.248Z",
      "updatedAt": "2025-03-09T02:41:13.248Z",
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}

Create a new custom field in an orgamization

post

/orgs/{organizationId}/custom-fields

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Body

namestring · min: 1 · max: 50required

Pattern: ^[a-z_\-0-9]+$

typestring · enumrequired

Options: text, number, boolean, tags, select:multi, select:single

titlestring · max: 100

descriptionstring · max: 200

placeholderstring · max: 100

optionsstring[]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/custom-fields' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "type": "text",
    "title": "text",
    "description": "text",
    "placeholder": "text",
    "options": [
      "text"
    ]
  }'

201

default

{
  "id": "text",
  "name": "text",
  "title": "text",
  "description": "text",
  "type": "text",
  "placeholder": "text",
  "options": [
    "text"
  ],
  "createdAt": "2025-03-09T02:41:13.248Z",
  "updatedAt": "2025-03-09T02:41:13.248Z",
  "urls": {
    "location": "https://example.com"
  }
}

Custom field created

Get specified organization member

Gets a specific member in an organization.

get

/orgs/{organizationId}/members/{userId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

userIdstringrequired

The unique ID of the User

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

default

{
  "id": "text",
  "role": "admin",
  "user": {
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "object": "user",
    "urls": {
      "location": "https://example.com"
    }
  },
  "disabled": true,
  "joinedAt": "2025-03-09T02:41:13.248Z",
  "lastSeenAt": "2025-03-09T02:41:13.248Z",
  "sso": true,
  "spaces": 1,
  "teams": 1,
  "object": "member"
}

Delete a member from an organization

Deletes a specific member from an organization

delete

/orgs/{organizationId}/members/{userId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

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}/members/{userId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

204

default

No body

The member was deleted from the organization.

Update specified organization member

Updates a specific member in an organization.

patch

/orgs/{organizationId}/members/{userId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

userIdstringrequired

The unique ID of the User

Body

roleone of

The role of a member in an organization, null for guests

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

default

{
  "id": "text",
  "role": "admin",
  "user": {
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "object": "user",
    "urls": {
      "location": "https://example.com"
    }
  },
  "disabled": true,
  "joinedAt": "2025-03-09T02:41:13.248Z",
  "lastSeenAt": "2025-03-09T02:41:13.248Z",
  "sso": true,
  "spaces": 1,
  "teams": 1,
  "object": "member"
}

The member has been updated

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

{
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-03-09T02:41:13.248Z",
  "object": "team"
}

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.

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

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

default

{
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-03-09T02:41:13.248Z",
  "object": "team"
}

The team has 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

rolestring · enum

"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

Update organization member's "last seen at" timestamp.

post

/orgs/{organizationId}/ping

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/ping' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "gitbookVisitorClaims": "text"
}

Organization member has been updated. Optionally returns a JWT token to attach to the user.

List organization SSO provider login information

Lists SSO login information configured for the specified organization.

get

/orgs/{organizationId}/sso

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

default

{
  "items": [
    {
      "id": "text",
      "label": "text",
      "startURL": "https://example.com"
    }
  ]
}

List organization members

Lists members for the specified organization.

get

/orgs/{organizationId}/members

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

orderstring · enum · default: desc

An order for the items in the list

Options: asc, desc

roleone of

The Role to filter the member list by

searchstring

A query to filter the member list (displayName and email)

sortstring · enum · default: joinedAt

The property to sort the results by. When sorting by lastSeenAt, only active members will be listed.

Options: joinedAt, lastSeenAt

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "role": "admin",
      "user": {
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "object": "user",
        "urls": {
          "location": "https://example.com"
        }
      },
      "disabled": true,
      "joinedAt": "2025-03-09T02:41:13.248Z",
      "lastSeenAt": "2025-03-09T02:41:13.248Z",
      "sso": true,
      "spaces": 1,
      "teams": 1,
      "object": "member"
    }
  ]
}

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 · max: 1000

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": [
    {
      "id": "text",
      "title": "text",
      "members": 1,
      "spaces": 1,
      "createdAt": "2025-03-09T02:41:13.248Z",
      "object": "team"
    }
  ]
}

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

titlestring · min: 1 · max: 64required

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

201

default

{
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-03-09T02:41:13.248Z",
  "object": "team"
}

Team has been created

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 · max: 1000

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": {
        "id": "text",
        "role": "admin",
        "user": {
          "id": "text",
          "displayName": "text",
          "email": "text",
          "photoURL": "text",
          "object": "user",
          "urls": {
            "location": "https://example.com"
          }
        },
        "disabled": true,
        "joinedAt": "2025-03-09T02:41:13.248Z",
        "lastSeenAt": "2025-03-09T02:41:13.248Z",
        "sso": true,
        "spaces": 1,
        "teams": 1,
        "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

addstring[]

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

membershipsobject

removestring[]

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

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 '{
    "add": [
      "text"
    ],
    "memberships": {
      "ANY_ADDITIONAL_PROPERTY": {
        "role": "owner"
      }
    },
    "remove": [
      "text"
    ]
  }'

204

default

No body

Members have been updated

List organization spaces

Lists spaces for the specified organization.

get

/orgs/{organizationId}/spaces

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "visibility": "public",
      "createdAt": "2025-03-09T02:41:13.248Z",
      "updatedAt": "2025-03-09T02:41:13.248Z",
      "deletedAt": "2025-03-09T02:41:13.248Z",
      "editMode": "live",
      "organization": "text",
      "parent": "text",
      "gitSync": {
        "installationProvider": "github",
        "integration": "text",
        "url": "text",
        "updatedAt": "2025-03-09T02:41:13.248Z"
      },
      "visitorAuth": {
        "backend": "custom"
      },
      "revision": "text",
      "defaultLevel": "admin",
      "comments": 1,
      "changeRequests": 1,
      "changeRequestsOpen": 1,
      "changeRequestsDraft": 1,
      "object": "space",
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "published": "https://example.com",
        "public": "https://example.com",
        "icon": "https://example.com"
      },
      "permissions": {
        "access": true,
        "admin": true,
        "edit": true,
        "comment": true,
        "merge": true,
        "review": true
      }
    }
  ]
}

Create an organization space

post

/orgs/{organizationId}/spaces

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Body

titlestring · max: 50

emojistring · emoji · max: 50

Unicode codepoint or character of the emoji

Example: 🎉

privatebooleanDeprecated

Private spaces are no longer supported by GitBook.

parentstring

ID of a parent collection

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/spaces' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "emoji": "🎉",
    "private": true,
    "parent": "text"
  }'

201

default

{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2025-03-09T02:41:13.248Z",
  "updatedAt": "2025-03-09T02:41:13.248Z",
  "deletedAt": "2025-03-09T02:41:13.248Z",
  "editMode": "live",
  "organization": "text",
  "parent": "text",
  "gitSync": {
    "installationProvider": "github",
    "integration": "text",
    "url": "text",
    "updatedAt": "2025-03-09T02:41:13.248Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "object": "space",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com",
    "public": "https://example.com",
    "icon": "https://example.com"
  },
  "permissions": {
    "access": true,
    "admin": true,
    "edit": true,
    "comment": true,
    "merge": true,
    "review": true
  }
}

Space created

List organization collections

Lists collections for the specified organization.

get

/orgs/{organizationId}/collections

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

nestedboolean · default: true

If true, all nested collections will be listed

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "title": "text",
      "description": "text",
      "organization": "text",
      "parent": "text",
      "defaultLevel": "admin",
      "object": "collection",
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com"
      },
      "permissions": {
        "admin": true,
        "create": true
      }
    }
  ]
}

Create an organization collection

post

/orgs/{organizationId}/collections

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Body

titlestring · max: 50

parentstring

ID of a parent collection

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/collections' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "parent": "text"
  }'

201

default

{
  "id": "text",
  "title": "text",
  "description": "text",
  "organization": "text",
  "parent": "text",
  "defaultLevel": "admin",
  "object": "collection",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  },
  "permissions": {
    "admin": true,
    "create": true
  }
}

Collection created

List organization SAML providers

Lists SAML providers configured for the specified organization.

get

/orgs/{organizationId}/saml

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "label": "text",
      "ssoURL": "https://example.com",
      "entityID": "text",
      "certificate": "text",
      "defaultTeam": {
        "id": "text",
        "title": "text",
        "members": 1,
        "spaces": 1,
        "createdAt": "2025-03-09T02:41:13.248Z",
        "object": "team"
      },
      "defaultRole": "admin",
      "createdAt": "2025-03-09T02:41:13.248Z",
      "object": "saml-provider",
      "service": {
        "acsURL": "https://example.com",
        "startURL": "https://example.com",
        "entityID": "text"
      },
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}

Create a new SAML provider in an orgamization

post

/orgs/{organizationId}/saml

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Body

labelstring · min: 1 · max: 30required

entityIDstring · max: 1024

certificatestring · max: 10000

ssoURLstring · uri · max: 2048

defaultTeamstring

defaultRoleone of

The role of a member in an organization, null for guests

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/saml' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "label": "text",
    "entityID": "text",
    "certificate": "text",
    "ssoURL": "https://example.com",
    "defaultTeam": "text",
    "defaultRole": "admin"
  }'

201

default

{
  "id": "text",
  "label": "text",
  "ssoURL": "https://example.com",
  "entityID": "text",
  "certificate": "text",
  "defaultTeam": {
    "id": "text",
    "title": "text",
    "members": 1,
    "spaces": 1,
    "createdAt": "2025-03-09T02:41:13.248Z",
    "object": "team"
  },
  "defaultRole": "admin",
  "createdAt": "2025-03-09T02:41:13.248Z",
  "object": "saml-provider",
  "service": {
    "acsURL": "https://example.com",
    "startURL": "https://example.com",
    "entityID": "text"
  },
  "urls": {
    "location": "https://example.com"
  }
}

SAML Provider created

Set a user as an SSO member of an organization

Use an invite to join an organization.

Get a custom field by its name

Delete a custom field in an organization

Update a custom field in an organization

Get a SAML provider in an organization by its ID

Delete a SAML provider in an organization

Update a SAML provider in an organization

Show child attributes

Show child attributes

Deletes an organization invite.

Update an organization invite.

Show child attributes

Show child attributes

Get an organization by its ID

Update an organization by its ID

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Invite users to a given organization based on a list of emails

Show child attributes

Show child attributes

Show available items

Get the list of organizations for the currently authenticated user

List invite links to an organization

Create a new organization invite

Show child attributes

Show child attributes

Show child attributes

Search content in an organization

Get the custom fields for spaces in an organization

Create a new custom field in an orgamization

Get specified organization member

Delete a member from an organization

Update specified organization member

Show child attributes

Show child attributes

Get specified organization team

Delete a team in an organization

Update specified organization team

Add or update a team membership

Delete members from a team

Update organization member's "last seen at" timestamp.

List organization SSO provider login information

List organization members

Show child attributes

Show child attributes

List organization teams

Create organization team

List team members

Updates members of an organization team

Show child attributes

List organization spaces

Create an organization space

List organization collections

Create an organization collection

List organization SAML providers

Create a new SAML provider in an orgamization

Show child attributes

Show child attributes