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

pathstring

Path in the published URL

visibility*ContentVisibility (enum)

• public: Anyone can access the content, and the content is indexed by search engines.
• unlisted: Anyone can access the content, and the content is not indexed by search engines
• share-link: Anyone with a secret token in the url can access the content.
• visitor-auth: Anyone authenticated through a JWT token can access the content.
• in-collection: Anyone who can access the parent collection can access the content. Only available for spaces in a collection.
• private: Authorized members can access the content.

publicunlistedshare-linkvisitor-authin-collectionprivate

publishingTypeenum

variants

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

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",
  "path": "text",
  "visibility": "public",
  "publishingType": "variants",
  "organization": "text",
  "parent": "text",
  "defaultLevel": "admin",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

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-09-16T06:13:16.396Z",
      "updatedAt": "2024-09-16T06:13:16.396Z",
      "deletedAt": "2024-09-16T06:13:16.396Z",
      "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-09-16T06:13:16.396Z",
          "completedAt": "2024-09-16T06:13:16.396Z",
          "error": "text"
        },
        "url": "text",
        "updatedAt": "2024-09-16T06:13:16.396Z"
      },
      "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

pathstring

Path in the published URL

visibility*ContentVisibility (enum)

• public: Anyone can access the content, and the content is indexed by search engines.
• unlisted: Anyone can access the content, and the content is not indexed by search engines
• share-link: Anyone with a secret token in the url can access the content.
• visitor-auth: Anyone authenticated through a JWT token can access the content.
• in-collection: Anyone who can access the parent collection can access the content. Only available for spaces in a collection.
• private: Authorized members can access the content.

publicunlistedshare-linkvisitor-authin-collectionprivate

publishingTypeenum

variants

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

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",
  "path": "text",
  "visibility": "public",
  "publishingType": "variants",
  "organization": "text",
  "parent": "text",
  "defaultLevel": "admin",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

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