Collection permissions

Manage which members and teams can access or contribute to a collection of spaces.

Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.

Invite to a collection

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

Body

application/json

or

Responses

204

OK

404

No team or user with the provided Id

application/json

post

/collections/{collectionId}/permissions

HTTPcURLJavaScriptPython

POST /v1/collections/{collectionId}/permissions HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "role": "admin",
  "teams": [
    "text"
  ]
}

No content

List an org team's permission in collection

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

Listing of teams who have been added to a collection.

application/json

get

/collections/{collectionId}/permissions/teams

HTTPcURLJavaScriptPython

GET /v1/collections/{collectionId}/permissions/teams HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Listing of teams who have been added to a collection.

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "permission": "admin",
      "team": {
        "object": "team",
        "id": "text",
        "title": "text",
        "members": 1,
        "spaces": 1,
        "createdAt": "2026-03-18T12:28:35.887Z",
        "permissions": {
          "admin": true,
          "view": true
        }
      }
    }
  ]
}

Remove an org team from a collection

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

teamIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

Responses

204

The team was not found in the collection

205

The team has been removed from the collection

delete

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

HTTPcURLJavaScriptPython

DELETE /v1/collections/{collectionId}/permissions/teams/{teamId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update an org team's permission in a collection

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

teamIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

Body

application/json

roleone ofOptional

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

string · enumOptional

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

Possible values:

or

nullOptional

Responses

204

Team permission was updated

404

No team found with the given ID

application/json

patch

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

HTTPcURLJavaScriptPython

PATCH /v1/collections/{collectionId}/permissions/teams/{teamId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "role": "admin"
}

No content

List collection user permissions

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

Listing of users who have been added to a collection.

application/json

404

No space found with the given Id

application/json

get

/collections/{collectionId}/permissions/users

HTTPcURLJavaScriptPython

GET /v1/collections/{collectionId}/permissions/users HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Remove a user from a collection

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

userIdstringRequired

The unique ID of the User

Responses

204

The user was not found in the collection

205

The user has been removed from the collection

delete

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

HTTPcURLJavaScriptPython

DELETE /v1/collections/{collectionId}/permissions/users/{userId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a collection user permission

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

userIdstringRequired

The unique ID of the User

Body

application/json

roleone ofOptional

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

string · enumOptional

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

Possible values:

or

nullOptional

Responses

204

User permission was updated

404

No user found with the given ID

application/json

patch

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

HTTPcURLJavaScriptPython

PATCH /v1/collections/{collectionId}/permissions/users/{userId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "role": "admin"
}

No content