Homepage
CommunityBlogLog inSign up

Organizations

Manage organizations and group users, spaces, and collections.

Get the list of organizations for the currently authenticated user

get
Authorizations
Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "organization",
      "id": "text",
      "title": "text",
      "createdAt": "2025-03-21T17:24:06.329Z",
      "emailDomains": [
        "text"
      ],
      "hostname": "text",
      "type": "business",
      "useCase": "internalDocs",
      "communityType": "nonProfit",
      "defaultRole": "admin",
      "defaultContent": {
        "type": "site",
        "site": "text"
      },
      "sso": true,
      "ai": true,
      "inviteLinks": true,
      "plan": "free_2024",
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "logo": "https://example.com"
      },
      "trial": {
        "status": "notapplicable",
        "endDate": "2025-03-21T17:24:06.329Z",
        "decision": "downgrade"
      },
      "customHostname": "text",
      "blocked": {
        "reason": "security"
      },
      "internal_isOnNewTrial": true,
      "internal_billingMigration": {
        "deadline": "2025-03-21T17:24:06.329Z",
        "discountPercent": 1,
        "discountEndDate": "2025-03-21T17:24:06.329Z"
      },
      "permissions": {
        "admin": true,
        "createContent": true
      }
    }
  ]
}

OK

Get an organization by its ID

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "organization",
  "id": "text",
  "title": "text",
  "createdAt": "2025-03-21T17:24:06.329Z",
  "emailDomains": [
    "text"
  ],
  "hostname": "text",
  "type": "business",
  "useCase": "internalDocs",
  "communityType": "nonProfit",
  "defaultRole": "admin",
  "defaultContent": {
    "type": "site",
    "site": "text"
  },
  "sso": true,
  "ai": true,
  "inviteLinks": true,
  "plan": "free_2024",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "trial": {
    "status": "notapplicable",
    "endDate": "2025-03-21T17:24:06.329Z",
    "decision": "downgrade"
  },
  "customHostname": "text",
  "blocked": {
    "reason": "security"
  },
  "internal_isOnNewTrial": true,
  "internal_billingMigration": {
    "deadline": "2025-03-21T17:24:06.329Z",
    "discountPercent": 1,
    "discountEndDate": "2025-03-21T17:24:06.329Z"
  },
  "permissions": {
    "admin": true,
    "createContent": true
  }
}

OK

Update an organization by its ID

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Body
titlestring · min: 2 · max: 255optional

Name of the organization

emailDomainsstring[]optional
hostnamestring · min: 3 · max: 32optional

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

defaultRoleone ofoptional

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.

defaultContentone ofoptional

logoone ofoptional

ssobooleanoptional
aibooleanoptional
inviteLinksbooleanoptional
Responses
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",
    "defaultContent": {
      "type": "site",
      "site": "text"
    },
    "logo": "https://example.com",
    "sso": true,
    "ai": true,
    "inviteLinks": true
  }'
{
  "object": "organization",
  "id": "text",
  "title": "text",
  "createdAt": "2025-03-21T17:24:06.329Z",
  "emailDomains": [
    "text"
  ],
  "hostname": "text",
  "type": "business",
  "useCase": "internalDocs",
  "communityType": "nonProfit",
  "defaultRole": "admin",
  "defaultContent": {
    "type": "site",
    "site": "text"
  },
  "sso": true,
  "ai": true,
  "inviteLinks": true,
  "plan": "free_2024",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "logo": "https://example.com"
  },
  "trial": {
    "status": "notapplicable",
    "endDate": "2025-03-21T17:24:06.329Z",
    "decision": "downgrade"
  },
  "customHostname": "text",
  "blocked": {
    "reason": "security"
  },
  "internal_isOnNewTrial": true,
  "internal_billingMigration": {
    "deadline": "2025-03-21T17:24:06.329Z",
    "discountPercent": 1,
    "discountEndDate": "2025-03-21T17:24:06.329Z"
  },
  "permissions": {
    "admin": true,
    "createContent": true
  }
}

The organization has been updated

List organization members

get

Lists members for the specified organization.

Authorizations
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

orderstring · enum · default: "desc"optional

An order for the items in the list

Options: asc, desc
roleone ofoptional

The Role to filter the member list by

"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.

searchstringoptional

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

sortstring · enum · default: "joinedAt"optional

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

Options: joinedAt, lastSeenAt
Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/members' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "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-03-21T17:24:06.329Z",
      "lastSeenAt": "2025-03-21T17:24:06.329Z",
      "sso": true,
      "spaces": 1,
      "teams": 1
    }
  ]
}

OK

Get specified organization member

get

Gets a specific member in an organization.

Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

userIdstringrequired

The unique ID of the User

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/members/{userId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "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-03-21T17:24:06.329Z",
  "lastSeenAt": "2025-03-21T17:24:06.329Z",
  "sso": true,
  "spaces": 1,
  "teams": 1
}

OK

Delete a member from an organization

delete

Deletes a specific member from an organization

Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

userIdstringrequired

The unique ID of the User

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

The member was deleted from the organization.

Update specified organization member

patch

Updates a specific member in an organization.

Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

userIdstringrequired

The unique ID of the User

Body
roleone ofoptional

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
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"
  }'
{
  "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-03-21T17:24:06.329Z",
  "lastSeenAt": "2025-03-21T17:24:06.329Z",
  "sso": true,
  "spaces": 1,
  "teams": 1
}

The member has been updated

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

post

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

Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

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

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

Set a user as an SSO member of an organization

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

userIdstringrequired

The unique ID of the User

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/members/{userId}/sso' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "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-03-21T17:24:06.329Z",
  "lastSeenAt": "2025-03-21T17:24:06.329Z",
  "sso": true,
  "spaces": 1,
  "teams": 1
}

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

List organization teams

get

Lists teams for the specified organization.

Authorizations
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
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/teams' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "team",
      "id": "text",
      "title": "text",
      "members": 1,
      "spaces": 1,
      "createdAt": "2025-03-21T17:24:06.329Z"
    }
  ]
}

OK

Create organization team

put

Creates a team in the specified organization.

Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Body
titlestring · min: 1 · max: 64required

Title of the team

membersstring[]optional

A list of organization member identifiers

Responses
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"
    ]
  }'
{
  "object": "team",
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-03-21T17:24:06.329Z"
}

Team has been created

Get specified organization team

get

Gets a specific team in an organization.

Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

teamIdstringrequired

The unique ID of the Team

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "team",
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-03-21T17:24:06.329Z"
}

OK

Delete a team in an organization

delete

Deletes a specific team in an organization

Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

teamIdstringrequired

The unique ID of the Team

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

The team was deleted from the organization.

Update specified organization team

patch

Updates a specific team in an organization.

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
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"
  }'
{
  "object": "team",
  "id": "text",
  "title": "text",
  "members": 1,
  "spaces": 1,
  "createdAt": "2025-03-21T17:24:06.329Z"
}

The team has been updated

List team members

get

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

Authorizations
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
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/teams/{teamId}/members' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "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-03-21T17:24:06.329Z",
        "lastSeenAt": "2025-03-21T17:24:06.329Z",
        "sso": true,
        "spaces": 1,
        "teams": 1
      },
      "team": {
        "role": "owner"
      }
    }
  ]
}

OK

Updates members of an organization 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
Path parameters
organizationIdstringrequired

The unique id of the organization

teamIdstringrequired

The unique ID of the Team

Body
addstring[]optional

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

membershipsobjectoptional

removestring[]optional

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

Responses
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"
    ]
  }'
No body

Members have been updated

Add or update a team membership

put

Add or updates member in the specified organization team.

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 · enumoptional

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

Options: owner, member
Responses
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"
  }'
No body

Member has been added to the team

Delete members from a team

delete

Deletes member from the specified organization team.

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

Member has been deleted from the team

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

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Body
emailsone of[]required

roleone ofoptional

Default role to set on newly invited members.

"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.

ssobooleanoptional

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

Responses
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 '{
    "emails": [
      "text"
    ],
    "role": "admin",
    "sso": true
  }'
{
  "users": [
    "text"
  ],
  "invited": 1,
  "failedSSOEmails": [
    "text"
  ]
}

OK

Use an invite to join an organization.

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

inviteIdstringrequired

The unique id of the invite

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

OK

List invite links to an organization

get
Authorizations
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

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/link-invites' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "invite",
      "id": "text",
      "role": "admin"
    }
  ]
}

List of invite links in the organization.

Create a new organization invite

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Body
one ofoptional

Responses
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"
  }'
{
  "object": "invite",
  "id": "text",
  "role": "admin"
}

The organization invite has been created

Deletes an organization invite.

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

inviteIdstringrequired

The unique id of the invite

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

The organization invite has been deleted

Update an organization invite.

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

inviteIdstringrequired

The unique id of the invite

Body
one ofoptional

Update role of an organization invite

Update level of an organization content invite

Responses
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"
  }'
{
  "object": "invite",
  "id": "text",
  "role": "admin"
}

The organization invite has been updated

Search content in an organization

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Query parameters
querystring · max: 512required
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/search?query=text' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "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"
          }
        }
      ]
    }
  ]
}

OK

List organization spaces

get

Lists spaces for the specified organization.

Authorizations
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

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/spaces' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "space",
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "visibility": "public",
      "createdAt": "2025-03-21T17:24:06.329Z",
      "updatedAt": "2025-03-21T17:24:06.329Z",
      "deletedAt": "2025-03-21T17:24:06.329Z",
      "editMode": "live",
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "published": "https://example.com",
        "public": "https://example.com",
        "icon": "https://example.com"
      },
      "organization": "text",
      "parent": "text",
      "gitSync": {
        "installationProvider": "github",
        "integration": "text",
        "url": "text",
        "updatedAt": "2025-03-21T17:24:06.329Z"
      },
      "visitorAuth": {
        "backend": "custom"
      },
      "revision": "text",
      "defaultLevel": "admin",
      "comments": 1,
      "changeRequests": 1,
      "changeRequestsOpen": 1,
      "changeRequestsDraft": 1,
      "permissions": {
        "access": true,
        "admin": true,
        "edit": true,
        "comment": true,
        "merge": true,
        "review": true
      }
    }
  ]
}

OK

Create an organization space

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Body
titlestring · max: 50optional
emojistring · emoji · max: 50optional

Unicode codepoint or character of the emoji

Example: 🎉
privatebooleanoptionalDeprecated

Private spaces are no longer supported by GitBook.

parentstringoptional

ID of a parent collection

Responses
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"
  }'
{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2025-03-21T17:24:06.329Z",
  "updatedAt": "2025-03-21T17:24:06.329Z",
  "deletedAt": "2025-03-21T17:24:06.329Z",
  "editMode": "live",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com",
    "public": "https://example.com",
    "icon": "https://example.com"
  },
  "organization": "text",
  "parent": "text",
  "gitSync": {
    "installationProvider": "github",
    "integration": "text",
    "url": "text",
    "updatedAt": "2025-03-21T17:24:06.329Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "permissions": {
    "access": true,
    "admin": true,
    "edit": true,
    "comment": true,
    "merge": true,
    "review": true
  }
}

Space created

List organization collections

get

Lists collections for the specified organization.

Authorizations
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

nestedboolean · default: trueoptional

If true, all nested collections will be listed

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/collections' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "collection",
      "id": "text",
      "title": "text",
      "description": "text",
      "organization": "text",
      "parent": "text",
      "defaultLevel": "admin",
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com"
      },
      "permissions": {
        "admin": true,
        "create": true
      }
    }
  ]
}

OK

Create an organization collection

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Body
titlestring · max: 50optional
parentstringoptional

ID of a parent collection

Responses
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"
  }'
{
  "object": "collection",
  "id": "text",
  "title": "text",
  "description": "text",
  "organization": "text",
  "parent": "text",
  "defaultLevel": "admin",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  },
  "permissions": {
    "admin": true,
    "create": true
  }
}

Collection created

Get the custom fields for spaces in an organization

get
Authorizations
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

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/custom-fields' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "id": "text",
      "name": "text",
      "title": "text",
      "description": "text",
      "type": "text",
      "placeholder": "text",
      "options": [
        "text"
      ],
      "createdAt": "2025-03-21T17:24:06.329Z",
      "updatedAt": "2025-03-21T17:24:06.329Z",
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}

OK

Create a new custom field in an orgamization

post
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: 100optional
descriptionstring · max: 200optional
placeholderstring · max: 100optional
optionsstring[] · min: 1 · max: 50optional
Responses
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"
    ]
  }'
{
  "id": "text",
  "name": "text",
  "title": "text",
  "description": "text",
  "type": "text",
  "placeholder": "text",
  "options": [
    "text"
  ],
  "createdAt": "2025-03-21T17:24:06.329Z",
  "updatedAt": "2025-03-21T17:24:06.329Z",
  "urls": {
    "location": "https://example.com"
  }
}

Custom field created

Get a custom field by its name

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

fieldNamestringrequired

The name of the custom field

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/custom-fields/{fieldName}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "id": "text",
  "name": "text",
  "title": "text",
  "description": "text",
  "type": "text",
  "placeholder": "text",
  "options": [
    "text"
  ],
  "createdAt": "2025-03-21T17:24:06.329Z",
  "updatedAt": "2025-03-21T17:24:06.329Z",
  "urls": {
    "location": "https://example.com"
  }
}

OK

Delete a custom field in an organization

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

fieldNamestringrequired

The name of the custom field

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

Custom field has been deleted

Update a custom field in an organization

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

fieldNamestringrequired

The name of the custom field

Body
titlestring · max: 100optional
descriptionstring · max: 200optional
placeholderstring · max: 100optional
optionsstring[] · min: 1 · max: 50optional
Responses
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"
    ]
  }'
{
  "id": "text",
  "name": "text",
  "title": "text",
  "description": "text",
  "type": "text",
  "placeholder": "text",
  "options": [
    "text"
  ],
  "createdAt": "2025-03-21T17:24:06.329Z",
  "updatedAt": "2025-03-21T17:24:06.329Z",
  "urls": {
    "location": "https://example.com"
  }
}

OK

List organization SAML providers

get

Lists SAML providers configured for the specified organization.

Authorizations
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

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/saml' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "saml-provider",
      "id": "text",
      "label": "text",
      "ssoURL": "https://example.com",
      "entityID": "text",
      "certificate": "text",
      "defaultTeam": {
        "object": "team",
        "id": "text",
        "title": "text",
        "members": 1,
        "spaces": 1,
        "createdAt": "2025-03-21T17:24:06.329Z"
      },
      "defaultRole": "admin",
      "createdAt": "2025-03-21T17:24:06.329Z",
      "service": {
        "acsURL": "https://example.com",
        "startURL": "https://example.com",
        "entityID": "text"
      },
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}

OK

Create a new SAML provider in an orgamization

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Body
labelstring · min: 1 · max: 30required
entityIDstring · max: 1024optional
certificatestring · max: 10000optional
ssoURLstring · uri · max: 2048optional
defaultTeamstringoptional
defaultRoleone ofoptional

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
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"
  }'
{
  "object": "saml-provider",
  "id": "text",
  "label": "text",
  "ssoURL": "https://example.com",
  "entityID": "text",
  "certificate": "text",
  "defaultTeam": {
    "object": "team",
    "id": "text",
    "title": "text",
    "members": 1,
    "spaces": 1,
    "createdAt": "2025-03-21T17:24:06.329Z"
  },
  "defaultRole": "admin",
  "createdAt": "2025-03-21T17:24:06.329Z",
  "service": {
    "acsURL": "https://example.com",
    "startURL": "https://example.com",
    "entityID": "text"
  },
  "urls": {
    "location": "https://example.com"
  }
}

SAML Provider created

Get a SAML provider in an organization by its ID

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

samlProviderIdstringrequired

The unique id of the SAML provider

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/saml/{samlProviderId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "saml-provider",
  "id": "text",
  "label": "text",
  "ssoURL": "https://example.com",
  "entityID": "text",
  "certificate": "text",
  "defaultTeam": {
    "object": "team",
    "id": "text",
    "title": "text",
    "members": 1,
    "spaces": 1,
    "createdAt": "2025-03-21T17:24:06.329Z"
  },
  "defaultRole": "admin",
  "createdAt": "2025-03-21T17:24:06.329Z",
  "service": {
    "acsURL": "https://example.com",
    "startURL": "https://example.com",
    "entityID": "text"
  },
  "urls": {
    "location": "https://example.com"
  }
}

OK

Delete a SAML provider in an organization

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

samlProviderIdstringrequired

The unique id of the SAML provider

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

SAML provider has been deleted

Update a SAML provider in an organization

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

samlProviderIdstringrequired

The unique id of the SAML provider

Body
labelstring · min: 1 · max: 30optional
entityIDstring · max: 1024optional
certificatestring · max: 10000optional
ssoURLstring · uri · max: 2048optional
defaultTeamstringoptional
defaultRoleone ofoptional

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
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"
  }'
{
  "object": "saml-provider",
  "id": "text",
  "label": "text",
  "ssoURL": "https://example.com",
  "entityID": "text",
  "certificate": "text",
  "defaultTeam": {
    "object": "team",
    "id": "text",
    "title": "text",
    "members": 1,
    "spaces": 1,
    "createdAt": "2025-03-21T17:24:06.329Z"
  },
  "defaultRole": "admin",
  "createdAt": "2025-03-21T17:24:06.329Z",
  "service": {
    "acsURL": "https://example.com",
    "startURL": "https://example.com",
    "entityID": "text"
  },
  "urls": {
    "location": "https://example.com"
  }
}

SAML provider has been updated

List organization SSO provider login information

get

Lists SSO login information configured for the specified organization.

Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sso' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "items": [
    {
      "id": "text",
      "label": "text",
      "startURL": "https://example.com"
    }
  ]
}

OK

Create a signed URL to upload a file

post

Generate a pre-signed URL that can be used to upload a file to storage

Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Body
fileobjectrequired

kindstring · enumrequired
Options: customization_font
Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/storage/upload' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "file": {
      "name": "text",
      "type": "text",
      "size": 1
    },
    "kind": "customization_font"
  }'
{
  "object": "storage-signed-url",
  "url": "https://example.com",
  "key": "text"
}

Successfully generated signed URL for file upload

List custom fonts in organization

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/fonts' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "id": "text",
      "fontFamily": "text",
      "fontFaces": [
        {
          "weight": 1,
          "sources": [
            {
              "url": "https://example.com",
              "format": "woff2"
            }
          ]
        }
      ]
    }
  ]
}

OK

Create a custom font in organization

put
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Body
fontFamilystring · min: 1 · max: 50required

The human-readable font-family name used in CSS (e.g., "Open Sans", "Playfair Display").

fontFacesobject[] · min: 1required

Array of font faces specifying weights and their corresponding storage keys. At least one font face with weight 400 (regular) must be provided.

Responses
curl -L \
  --request PUT \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/fonts' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "fontFamily": "text",
    "fontFaces": [
      {
        "weight": 1,
        "storageKey": "text"
      }
    ]
  }'
{
  "id": "text",
  "fontFamily": "text",
  "fontFaces": [
    {
      "weight": 1,
      "sources": [
        {
          "url": "https://example.com",
          "format": "woff2"
        }
      ]
    }
  ]
}

Custom font created successfully.

Delete a custom font from an organization

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

fontIdstringrequired

The unique ID of a font

Responses
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/fonts/{fontId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No body

Custom font deleted successfully.

Was this helpful?