Collections

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

Last updated 8 days ago

Was this helpful?

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

cURL

JavaScript

Python

HTTP

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

200

default

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

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

The number of results per page

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "title": "text",
      "visibility": "public",
      "createdAt": "2025-02-15T12:39:56.496Z",
      "updatedAt": "2025-02-15T12:39:56.496Z",
      "deletedAt": "2025-02-15T12:39:56.496Z",
      "editMode": "live",
      "gitSync": {
        "installationProvider": "github",
        "integration": "text",
        "url": "text",
        "updatedAt": "2025-02-15T12:39:56.496Z"
      },
      "visitorAuth": {
        "backend": "custom"
      },
      "defaultLevel": "admin",
      "id": "text",
      "emoji": "🎉",
      "organization": "text",
      "parent": "text",
      "revision": "text",
      "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
      }
    }
  ]
}

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

cURL

JavaScript

Python

HTTP

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

200

default

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

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

The number of results per page

roleenum

"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

cURL

JavaScript

Python

HTTP

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

200

default

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