The State of Docs Survey 2025. Use your voice to prove why docs matter:
Take the survey
Product
PricingLog inSign up

Collections

Organize and manage collections for your spaces.

Get the details about a collection using its ID

get
Authorizations
Path parameters
collectionIdstringrequired

The unique id of the collection

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "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

Deletes a collection

delete
Authorizations
Path parameters
collectionIdstringrequired

The unique id of the collection

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

Collection has been deleted

Update the details of a collection

patch
Authorizations
Path parameters
collectionIdstringrequired

The unique id of the collection

Body
titlestring · max: 50optional

Title of the collection

descriptionstring · max: 100optional

Description of the collection

defaultLevelone ofoptional

Default level for a piece of content

"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/collections/{collectionId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "description": "text",
    "defaultLevel": "admin"
  }'
{
  "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
  }
}

The collection has been updated

List all the spaces in a collection by its ID.

get
Authorizations
Path parameters
collectionIdstringrequired

The unique id of the collection

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/collections/{collectionId}/spaces' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "space",
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "visibility": "public",
      "createdAt": "2025-04-03T20:37:46.046Z",
      "updatedAt": "2025-04-03T20:37:46.046Z",
      "deletedAt": "2025-04-03T20:37:46.046Z",
      "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": {
        "repoName": "text",
        "installationProvider": "github",
        "integration": "text",
        "url": "text",
        "updatedAt": "2025-04-03T20:37:46.046Z"
      },
      "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

Move a collection to a new position.

post
Authorizations
Path parameters
collectionIdstringrequired

The unique id of the collection

Body
parentstring | nullableoptional

The unique id of the parent collection

positionobjectoptional

Where to move the collection. By default, it will be moved at the end.

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/move' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "parent": "text",
    "position": {
      "before": {
        "type": "space",
        "space": "text"
      },
      "after": {
        "type": "space",
        "space": "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 moved

Transfer a collection to another organization.

post
Authorizations
Path parameters
collectionIdstringrequired

The unique id of the collection

Body
organizationstringrequired

The unique id of the target organization

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/transfer' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "organization": "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 transferred

Invite to a collection

post
Authorizations
Path parameters
collectionIdstringrequired

The unique id of the collection

Body
roleone ofrequired

Role to set.

"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/collections/{collectionId}/permissions' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "role": "admin",
    "teams": [
      "text"
    ]
  }'
No body

OK

Remove a team from a collection

delete
Authorizations
Path parameters
collectionIdstringrequired

The unique id of the collection

teamIdstringrequired

The unique ID of the Team

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

The team has been removed from the collection

Update a team's permission a collection

patch
Authorizations
Path parameters
collectionIdstringrequired

The unique id of the collection

teamIdstringrequired

The unique ID of the Team

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/collections/{collectionId}/permissions/teams/{teamId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "role": "admin"
  }'
No body

Team permission was updated

Remove a user from a collection

delete
Authorizations
Path parameters
collectionIdstringrequired

The unique id of the collection

userIdstringrequired

The unique ID of the User

Responses
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/permissions/users/{userId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No body

The user has been removed from the collection

Update a user's permission a collection

patch
Authorizations
Path parameters
collectionIdstringrequired

The unique id of the collection

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/collections/{collectionId}/permissions/users/{userId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "role": "admin"
  }'
No body

User permission was updated

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

Was this helpful?