Collections

A collection in GitBook is the entity of a group that a space can belong to.

Get the details about a collection using its ID

get

/collections/{collectionId}

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

default

200

{
  "id": "text",
  "title": "text",
  "description": "text",
  "organization": "text",
  "parent": "text",
  "defaultLevel": "admin",
  "object": "collection",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  },
  "permissions": {
    "admin": true,
    "create": true
  }
}

OK

List all the spaces in a collection by its ID.

get

/collections/{collectionId}/spaces

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/spaces' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

200

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "visibility": "public",
      "createdAt": "2025-02-27T07:12:47.208Z",
      "updatedAt": "2025-02-27T07:12:47.208Z",
      "deletedAt": "2025-02-27T07:12:47.208Z",
      "editMode": "live",
      "organization": "text",
      "parent": "text",
      "gitSync": {
        "installationProvider": "github",
        "integration": "text",
        "url": "text",
        "updatedAt": "2025-02-27T07:12:47.208Z"
      },
      "visitorAuth": {
        "backend": "custom"
      },
      "revision": "text",
      "defaultLevel": "admin",
      "comments": 1,
      "changeRequests": 1,
      "changeRequestsOpen": 1,
      "changeRequestsDraft": 1,
      "object": "space",
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "published": "https://example.com",
        "public": "https://example.com",
        "icon": "https://example.com"
      },
      "permissions": {
        "access": true,
        "admin": true,
        "edit": true,
        "comment": true,
        "merge": true,
        "review": true
      }
    }
  ]
}

OK

Get the details about a collection using its ID

get

/collections/{collectionId}

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

default

200

{
  "id": "text",
  "title": "text",
  "description": "text",
  "organization": "text",
  "parent": "text",
  "defaultLevel": "admin",
  "object": "collection",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  },
  "permissions": {
    "admin": true,
    "create": true
  }
}

OK

List permissions for all users in a collection.

get

/collections/{collectionId}/permissions/aggregate

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

rolestring · enum

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

Options: admin, create, edit, review, comment, read

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/permissions/aggregate' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

200

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "permission": "admin",
      "user": {
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "object": "user",
        "urls": {
          "location": "https://example.com"
        }
      }
    }
  ]
}

Listing of users who can access the collections.