Site permissions

Manage which members and teams can access or contribute to a docs site.

Invite, remove, or update users and teams permissions for a site. This provides a way to tightly control collaboration and visibility among your teammates.

Invite a user or a team to a site

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

application/json

or

Responses

204

OK

No content

404

No team or user with the provided Id

application/json

post

/orgs/{organizationId}/sites/{siteId}/permissions

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/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 a site

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

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

application/json

404

No site was found with the given Id

application/json

get

/orgs/{organizationId}/sites/{siteId}/permissions/teams

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/permissions/teams HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "permission": "admin",
      "team": {
        "object": "team",
        "id": "text",
        "title": "text",
        "members": 1,
        "spaces": 1,
        "createdAt": "2026-02-16T19:40:11.033Z",
        "permissions": {
          "admin": true,
          "view": true
        }
      }
    }
  ]
}

Remove an org team from a site

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

teamIdstringRequired

The unique ID of the Team

Responses

204

The team was not found in the site

No content

205

The team has been removed from the site

delete

/orgs/{organizationId}/sites/{siteId}/permissions/teams/{teamId}

HTTPcURLJavaScriptPython

DELETE /v1/orgs/{organizationId}/sites/{siteId}/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 site

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

teamIdstringRequired

The unique ID of the Team

Body

application/json

rolestring · 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:

Responses

204

Team permission was updated

No content

404

No team found with the given ID

application/json

patch

/orgs/{organizationId}/sites/{siteId}/permissions/teams/{teamId}

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/sites/{siteId}/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