Collections

Organize and manage collections for your spaces.

Was this helpful?

Invite to a collection

post

/collections/{collectionId}/permissions

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Body

roleone ofrequired

Role to set.

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

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/permissions' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "role": "admin",
    "teams": [
      "text"
    ]
  }'

204

404

default

No body

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

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

Deletes a collection

delete

/collections/{collectionId}

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Responses

application/json

cURL

JavaScript

Python

HTTP

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

205

default

No body

Collection has been deleted

Update the details of a collection

patch

/collections/{collectionId}

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Body

titlestring · max: 50

Title of the collection

descriptionstring · max: 100

Description of the collection

defaultLevelone of

Default level for a piece of content

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "description": "text",
    "defaultLevel": "admin"
  }'

200

default

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

The collection has been updated

Move a collection to a new position.

post

/collections/{collectionId}/move

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Body

parentstring | nullable

The unique id of the parent collection

positionobject

Where to move the collection. By default, it will be moved at the end.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/move' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "parent": "text",
    "position": {
      "before": {
        "space": "text",
        "type": "space"
      },
      "after": {
        "space": "text",
        "type": "space"
      }
    }
  }'

200

400

404

409

default

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

Collection moved

Transfer a collection to another organization.

post

/collections/{collectionId}/transfer

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Body

organizationstringrequired

The unique id of the target organization

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/transfer' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "organization": "text"
  }'

200

404

409

412

default

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

Collection transferred

Remove a team from a collection

delete

/collections/{collectionId}/permissions/teams/{teamId}

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

teamIdstringrequired

The unique ID of the Team

Responses

application/json

cURL

JavaScript

Python

HTTP

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

205

404

default

No body

The team has been removed from the collection

Update a team's permission a collection

patch

/collections/{collectionId}/permissions/teams/{teamId}

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

teamIdstringrequired

The unique ID of the Team

Body

roleone of

The role of a member in an organization, null for guests

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/permissions/teams/{teamId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "role": "admin"
  }'

204

404

default

No body

Team permission was updated

Remove a user from a collection

delete

/collections/{collectionId}/permissions/users/{userId}

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

userIdstringrequired

The unique ID of the User

Responses

application/json

cURL

JavaScript

Python

HTTP

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

205

404

default

No body

The user has been removed from the collection

Update a user's permission a collection

patch

/collections/{collectionId}/permissions/users/{userId}

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

userIdstringrequired

The unique ID of the User

Body

roleone of

The role of a member in an organization, null for guests

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/permissions/users/{userId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "role": "admin"
  }'

204

404

default

No body

User permission was updated

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

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": [
    {
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "visibility": "public",
      "createdAt": "2025-03-09T02:22:29.731Z",
      "updatedAt": "2025-03-09T02:22:29.731Z",
      "deletedAt": "2025-03-09T02:22:29.731Z",
      "editMode": "live",
      "organization": "text",
      "parent": "text",
      "gitSync": {
        "installationProvider": "github",
        "integration": "text",
        "url": "text",
        "updatedAt": "2025-03-09T02:22:29.731Z"
      },
      "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
      }
    }
  ]
}

List organization collections

Lists collections for the specified organization.

get

/orgs/{organizationId}/collections

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

nestedboolean · default: true

If true, all nested collections will be listed

Responses

application/json

cURL

JavaScript

Python

HTTP

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

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "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
      }
    }
  ]
}

Create an organization collection

post

/orgs/{organizationId}/collections

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Body

titlestring · max: 50

parentstring

ID of a parent collection

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/collections' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "parent": "text"
  }'

201

default

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

Collection created

Invite to a collection

Show child attributes

Show child attributes

Get the details about a collection using its ID

Deletes a collection

Update the details of a collection

Show child attributes

Show child attributes

Show child attributes

Move a collection to a new position.

Show child attributes

Transfer a collection to another organization.

Remove a team from a collection

Update a team's permission a collection

Show child attributes

Show child attributes

Remove a user from a collection

Update a user's permission a collection

Show child attributes

Show child attributes

List all the spaces in a collection by its ID.

List organization collections

Create an organization collection