Collections

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

GET a specific collection

Get the details about a collection using its ID

GEThttps://api.gitbook.com/v1/collections/{collectionId}

Authorization

user

Path parameters

collectionId*string

The unique id of the collection

Response

200default

OK

Body

application/json

object*enum

Type of Object, always equals to "collection"

collection

id*string

Unique identifier for the collection

title*CollectionTitle (string)

Title of the collection

descriptionCollectionDescription (string)

Description of the collection

organization*string

ID of the organization owning this collection

parentstring

ID of the parent collection, if any

defaultLevel*DefaultLevel (one of)

Default level for a piece of content

MemberRole (enum)nullable enumenum

urls*object

URLs associated with the object

permissions*object

The set of permissions for the collection

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/collections/{collectionId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200default

{
  "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": false,
    "create": false
  }
}

GET spaces in a collection

List all the spaces in a collection by its ID.

GEThttps://api.gitbook.com/v1/collections/{collectionId}/spaces

Authorization

user

Path parameters

collectionId*string

The unique id of the collection

Query parameters

Response

200default

OK

Body

application/json

nextobject

countnumber

Total count of objects in the list

items*array of Space (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/collections/{collectionId}/spaces', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200default

{
  "next": {
    "page": "text"
  },
  "count": 0,
  "items": [
    {
      "object": "space",
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "visibility": "public",
      "createdAt": "2024-11-21T07:20:19.069Z",
      "updatedAt": "2024-11-21T07:20:19.069Z",
      "deletedAt": "2024-11-21T07:20:19.069Z",
      "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": {
        "installationProvider": "text",
        "operation": {
          "state": "running",
          "startedAt": "2024-11-21T07:20:19.069Z",
          "completedAt": "2024-11-21T07:20:19.069Z",
          "error": "text"
        },
        "url": "text",
        "updatedAt": "2024-11-21T07:20:19.069Z"
      },
      "visitorAuth": {
        "backend": "custom"
      },
      "revision": "text",
      "defaultLevel": "admin"
    }
  ]
}

Get the details about a collection using its ID

GEThttps://api.gitbook.com/v1/collections/{collectionId}

Authorization

user

Path parameters

collectionId*string

The unique id of the collection

Response

200default

OK

Body

application/json

object*enum

Type of Object, always equals to "collection"

collection

id*string

Unique identifier for the collection

title*CollectionTitle (string)

Title of the collection

descriptionCollectionDescription (string)

Description of the collection

organization*string

ID of the organization owning this collection

parentstring

ID of the parent collection, if any

defaultLevel*DefaultLevel (one of)

Default level for a piece of content

MemberRole (enum)nullable enumenum

urls*object

URLs associated with the object

permissions*object

The set of permissions for the collection

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/collections/{collectionId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200default

{
  "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": false,
    "create": false
  }
}

GET permissions for all users in a collection

List permissions for all users in a collection.

GEThttps://api.gitbook.com/v1/collections/{collectionId}/permissions/aggregate

Authorization

user

Path parameters

collectionId*string

The unique id of the collection

Query parameters

Response

200default

Listing of users who can access the collections.

Body

application/json

nextobject

countnumber

Total count of objects in the list

items*array of UserContentPermission (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/collections/{collectionId}/permissions/aggregate', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200default

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