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

application/json

objectoptional

get

HTTPcURLJavaScriptPython

GET /v1/collections/{collectionId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

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

Delete a collection

delete

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Responses

delete

HTTPcURLJavaScriptPython

DELETE /v1/collections/{collectionId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

205

Collection has been deleted

No Content

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

application/json

objectoptional

patch

HTTPcURLJavaScriptPython

PATCH /v1/collections/{collectionId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 60

{
  "title": "text",
  "description": "text",
  "defaultLevel": "admin"
}

200

The collection has been updated

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

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

application/json

all ofoptional

get

HTTPcURLJavaScriptPython

GET /v1/collections/{collectionId}/spaces HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "space",
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "visibility": "public",
      "createdAt": "2025-04-16T04:38:07.479Z",
      "updatedAt": "2025-04-16T04:38:07.479Z",
      "deletedAt": "2025-04-16T04:38:07.479Z",
      "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-16T04:38:07.479Z"
      },
      "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
      }
    }
  ]
}

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

application/json

objectoptional

application/json

application/json

application/json

post

HTTPcURLJavaScriptPython

POST /v1/collections/{collectionId}/move HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 111

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

Transfer a collection

post

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Body

organizationstringrequired

The unique id of the target organization

Responses

application/json

objectoptional

application/json

application/json

application/json

post

HTTPcURLJavaScriptPython

POST /v1/collections/{collectionId}/transfer HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 23

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

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

application/json

all ofoptional

get

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/collections HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

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

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

application/json

objectoptional

post

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/collections HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 32

{
  "title": "text",
  "parent": "text"
}

201

Collection created

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