Homepage
CommunityPricingBlogGitBook Docs

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
Path parameters
collectionId*string

The unique id of the collection

Response

OK

Body
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

urls*object

URLs associated with the object

Request
const response = await fetch('https://api.gitbook.com/v1/collections/{collectionId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();
Response
{
  "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
Path parameters
collectionId*string

The unique id of the collection

Query parameters
Response

OK

Body
nextobject
countnumber

Total count of objects in the list

items*array of Space (object)
Request
const response = await fetch('https://api.gitbook.com/v1/collections/{collectionId}/spaces', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();
Response
{
  "next": {
    "page": "text"
  },
  "count": 0,
  "items": [
    {
      "object": "space",
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "visibility": "public",
      "createdAt": "2024-10-22T08:06:15.245Z",
      "updatedAt": "2024-10-22T08:06:15.245Z",
      "deletedAt": "2024-10-22T08:06:15.245Z",
      "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-10-22T08:06:15.245Z",
          "completedAt": "2024-10-22T08:06:15.245Z",
          "error": "text"
        },
        "url": "text",
        "updatedAt": "2024-10-22T08:06:15.245Z"
      },
      "visitorAuth": {
        "backend": "custom"
      },
      "revision": "text",
      "defaultLevel": "admin"
    }
  ]
}

Get the details about a collection using its ID

GEThttps://api.gitbook.com/v1/collections/{collectionId}
Authorization
Path parameters
collectionId*string

The unique id of the collection

Response

OK

Body
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

urls*object

URLs associated with the object

Request
const response = await fetch('https://api.gitbook.com/v1/collections/{collectionId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();
Response
{
  "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
Path parameters
collectionId*string

The unique id of the collection

Query parameters
Response

Listing of users who can access the collections.

Body
nextobject
countnumber

Total count of objects in the list

items*array of UserContentPermission (object)
Request
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
{
  "next": {
    "page": "text"
  },
  "count": 0,
  "items": [
    {
      "permission": "admin",
      "user": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      }
    }
  ]
}

Last updated