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.
Type of Object, always equals to "collection"
Unique identifier for the collection
Title of the collection
Description of the collection
ID of the organization owning this collection
ID of the parent collection, if any
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.
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": { "view": true, "admin": true, "viewInviteLinks": true, "create": true } }The unique id of the collection
OK
GET /v1/collections/{collectionId} HTTP/1.1 Host: api.gitbook.com Authorization: Bearer YOUR_SECRET_TOKEN Accept: */* 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": { "view": true, "admin": true, "viewInviteLinks": true, "create": true } }The unique id of the collection
Collection did not exist
No content
Collection has been deleted
DELETE /v1/collections/{collectionId} HTTP/1.1 Host: api.gitbook.com Authorization: Bearer YOUR_SECRET_TOKEN Accept: */* No content
The unique id of the collection
Title of the collection
Description of the collection
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.
The collection has been updated
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" }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": { "view": true, "admin": true, "viewInviteLinks": true, "create": true } }The unique id of the collection
Identifier of the page results to fetch.
The number of results per page
OK
GET /v1/collections/{collectionId}/spaces HTTP/1.1 Host: api.gitbook.com Authorization: Bearer YOUR_SECRET_TOKEN Accept: */* OK
{ "next": { "page": "text" }, "count": 1, "items": [ { "object": "space", "id": "text", "title": "text", "emoji": "🎉", "visibility": "public", "createdAt": "2025-10-10T11:03:45.016Z", "updatedAt": "2025-10-10T11:03:45.016Z", "deletedAt": "2025-10-10T11:03:45.016Z", "editMode": "live", "mergeRules": { "type": "inherit" }, "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", "language": "en", "gitSync": { "repoName": "text", "installationProvider": "github", "integration": "text", "url": "text", "updatedAt": "2025-10-10T11:03:45.016Z" }, "visitorAuth": { "backend": "custom" }, "revision": "text", "defaultLevel": "admin", "comments": 1, "changeRequests": 1, "changeRequestsOpen": 1, "changeRequestsDraft": 1, "permissions": { "view": true, "access": true, "admin": true, "viewInviteLinks": true, "edit": true, "triggerGitSync": true, "comment": true, "merge": true, "review": true, "installIntegration": true } } ] }The unique id of the collection
The unique id of the parent collection
Collection moved
Invalid position space or collection provided
No matching Collection found for given ID
Operation would not result in any update
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": { "view": true, "admin": true, "viewInviteLinks": true, "create": true } }The unique id of the collection
The unique id of the target organization
Collection transferred
No matching Collection found for given ID
Transfer would not result in any update
The collection cannot be moved.
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": { "view": true, "admin": true, "viewInviteLinks": true, "create": true } }The unique id of the organization
Identifier of the page results to fetch.
The number of results per page
If true, all nested collections will be listed
trueOK
GET /v1/orgs/{organizationId}/collections HTTP/1.1 Host: api.gitbook.com Authorization: Bearer YOUR_SECRET_TOKEN Accept: */* 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": { "view": true, "admin": true, "viewInviteLinks": true, "create": true } } ] }The unique id of the organization
ID of a parent collection
Collection created
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" }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": { "view": true, "admin": true, "viewInviteLinks": true, "create": true } }Was this helpful?