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 grouped sets of spaces for better content structure.

Collections let you bundle multiple spaces under a unified entity, making large-scale content easier to handle. You can sort content by subject, department, or any grouping logic.

The Collection object

Attributes
objectstring · enumrequired

Type of Object, always equals to "collection"

Available options:
idstringrequired

Unique identifier for the collection

titlestring · max: 50required

Title of the collection

descriptionstring · max: 100optional

Description of the collection

organizationstringrequired

ID of the organization owning this collection

parentstringoptional

ID of the parent collection, if any

defaultLevelone ofrequired

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.

urlsobjectrequired

URLs associated with the object

permissionsobjectrequired

The set of permissions for the collection

The Collection object

{
  "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
  }
}

Get a collection by 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

Delete 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 Content

Collection has been deleted

Update 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 collection spaces

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-16T23:15:52.121Z",
      "updatedAt": "2025-04-16T23:15:52.121Z",
      "deletedAt": "2025-04-16T23:15:52.121Z",
      "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-16T23:15:52.121Z"
      },
      "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

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

List all collections

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

nestedbooleanoptional

If true, all nested collections will be listed

Default: true
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 a 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?