Collection teams

Allocate team-based permissions to your collections.

Assign entire teams to a collection for easier role and permission management. Perfect for larger organizations looking to streamline content access.

List a collection team permissions

get

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Query parameters

pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

200

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "permission": "admin",
      "team": {
        "object": "team",
        "id": "text",
        "title": "text",
        "members": 1,
        "spaces": 1,
        "createdAt": "2025-04-12T21:04:01.096Z"
      }
    }
  ]
}

Listing of teams who have been added to a collection.

Remove a team from a collection

delete

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

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

205

404

205

No Content

The team has been removed from the collection

Update a collection team permission

patch

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

teamIdstringrequired

The unique ID of the Team

Body

roleone ofoptional

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

"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

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

204

No Content

Team permission was updated