> For the complete documentation index, see [llms.txt](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/developers/gitbook-api/api-reference/collections/collection-permissions.md).

# Collection permissions

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

## POST /collections/{collectionId}/permissions

> Invite to a collection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collection-permissions","description":"Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"InviteUsersAndTeams":{"type":"object","properties":{"role":{"description":"Role to set.","$ref":"#/components/schemas/MemberRoleOrGuest"}},"anyOf":[{"type":"object","properties":{"teams":{"type":"array","minItems":1,"items":{"type":"string","description":"The ID of the team to be invited"}}},"required":["teams"]},{"type":"object","properties":{"users":{"type":"array","minItems":1,"items":{"type":"string","description":"The ID of the user to be invited"}}},"required":["users"]}],"required":["role"]},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/collections/{collectionId}/permissions":{"post":{"operationId":"inviteToCollection","summary":"Invite to a collection","tags":["collection-permissions"],"parameters":[{"$ref":"#/components/parameters/collectionId"}],"responses":{"204":{"description":"OK"},"404":{"description":"No team or user with the provided Id","$ref":"#/components/responses/NotFoundError"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteUsersAndTeams"}}}}}}}}
```

## GET /collections/{collectionId}/permissions/teams

> List an org team's permission in collection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collection-permissions","description":"Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}},"listPage":{"name":"page","in":"query","description":"Identifier of the page results to fetch.","schema":{"type":"string"}},"listLimit":{"name":"limit","in":"query","description":"The number of results per page","schema":{"type":"number","minimum":0,"maximum":1000}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"List":{"type":"object","properties":{"next":{"type":"object","properties":{"page":{"type":"string","description":"Unique identifier to query the next results page"}},"required":["page"]},"count":{"type":"number","description":"Total count of objects in the list"}}},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]},"OrganizationTeam":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"team\"","enum":["team"]},"id":{"type":"string","description":"Unique identifier for the team."},"title":{"$ref":"#/components/schemas/OrganizationTeamTitle"},"members":{"type":"integer","description":"Count of members in this team."},"spaces":{"type":"number","description":"Count of spaces this team has access to."},"createdAt":{"description":"Date at which the team was created.","$ref":"#/components/schemas/Timestamp"},"permissions":{"type":"object","description":"The set of permissions for the team","properties":{"admin":{"type":"boolean","description":"Can the user manage the team"},"view":{"type":"boolean","description":"Can the user view the team and list its members"}},"required":["admin","view"]}},"required":["object","id","title","members","spaces","createdAt","permissions"]},"OrganizationTeamTitle":{"type":"string","description":"Title of the team","minLength":1,"maxLength":64},"Timestamp":{"type":"string","format":"date-time"}}},"paths":{"/collections/{collectionId}/permissions/teams":{"get":{"operationId":"listTeamPermissionsInCollection","summary":"List an org team's permission in collection","tags":["collection-permissions"],"parameters":[{"$ref":"#/components/parameters/collectionId"},{"$ref":"#/components/parameters/listPage"},{"$ref":"#/components/parameters/listLimit"}],"responses":{"200":{"description":"Listing of teams who have been added to a collection.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","description":"Permission of a team in a content.","properties":{"permission":{"$ref":"#/components/schemas/MemberRole"},"team":{"$ref":"#/components/schemas/OrganizationTeam"}},"required":["permission","team"]}}}}]}}}}}}}}}
```

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

> Remove an org team from a collection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collection-permissions","description":"Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}},"teamId":{"name":"teamId","in":"path","required":true,"description":"The unique ID of the Team","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"}}},"paths":{"/collections/{collectionId}/permissions/teams/{teamId}":{"delete":{"operationId":"removeTeamFromCollection","summary":"Remove an org team from a collection","tags":["collection-permissions"],"parameters":[{"$ref":"#/components/parameters/collectionId"},{"$ref":"#/components/parameters/teamId"}],"responses":{"204":{"description":"The team was not found in the collection"},"205":{"description":"The team has been removed from the collection"}}}}}}
```

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

> Update an org team's permission in a collection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collection-permissions","description":"Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}},"teamId":{"name":"teamId","in":"path","required":true,"description":"The unique ID of the Team","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/collections/{collectionId}/permissions/teams/{teamId}":{"patch":{"operationId":"updateTeamPermissionInCollection","summary":"Update an org team's permission in a collection","tags":["collection-permissions"],"parameters":[{"$ref":"#/components/parameters/collectionId"},{"$ref":"#/components/parameters/teamId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/MemberRoleOrGuest"}}}}}},"responses":{"204":{"description":"Team permission was updated"},"404":{"description":"No team found with the given ID","$ref":"#/components/responses/NotFoundError"}}}}}}
```

## GET /collections/{collectionId}/permissions/users

> List collection user permissions

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collection-permissions","description":"Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}},"listPage":{"name":"page","in":"query","description":"Identifier of the page results to fetch.","schema":{"type":"string"}},"listLimit":{"name":"limit","in":"query","description":"The number of results per page","schema":{"type":"number","minimum":0,"maximum":1000}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"List":{"type":"object","properties":{"next":{"type":"object","properties":{"page":{"type":"string","description":"Unique identifier to query the next results page"}},"required":["page"]},"count":{"type":"number","description":"Total count of objects in the list"}}},"UserContentPermission":{"type":"object","description":"Permission of a user in a content.","properties":{"permission":{"$ref":"#/components/schemas/MemberRole"},"user":{"$ref":"#/components/schemas/User"}},"required":["permission","user"]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]},"User":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"user\"","enum":["user"]},"id":{"type":"string","description":"Unique identifier for the user"},"displayName":{"type":"string","description":"Full name for the user"},"email":{"type":"string","description":"Email address of the user"},"photoURL":{"type":"string","description":"URL of the user's profile picture"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the user in the API","format":"uri"}},"required":["location"]}},"required":["object","id","displayName","urls"]}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/collections/{collectionId}/permissions/users":{"get":{"operationId":"listUserPermissionsInCollection","summary":"List collection user permissions","tags":["collection-permissions"],"parameters":[{"$ref":"#/components/parameters/collectionId"},{"$ref":"#/components/parameters/listPage"},{"$ref":"#/components/parameters/listLimit"}],"responses":{"200":{"description":"Listing of users who have been added to a collection.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UserContentPermission"}}}}]}}}},"404":{"description":"No space found with the given Id","$ref":"#/components/responses/NotFoundError"}}}}}}
```

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

> Remove a user from a collection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collection-permissions","description":"Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}},"userId":{"name":"userId","in":"path","required":true,"description":"The unique ID of the User","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"}}},"paths":{"/collections/{collectionId}/permissions/users/{userId}":{"delete":{"operationId":"removeUserFromCollection","summary":"Remove a user from a collection","tags":["collection-permissions"],"parameters":[{"$ref":"#/components/parameters/collectionId"},{"$ref":"#/components/parameters/userId"}],"responses":{"204":{"description":"The user was not found in the collection"},"205":{"description":"The user has been removed from the collection"}}}}}}
```

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

> Update a collection user permission

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collection-permissions","description":"Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}},"userId":{"name":"userId","in":"path","required":true,"description":"The unique ID of the User","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/collections/{collectionId}/permissions/users/{userId}":{"patch":{"operationId":"updateUserPermissionInCollection","summary":"Update a collection user permission","tags":["collection-permissions"],"parameters":[{"$ref":"#/components/parameters/collectionId"},{"$ref":"#/components/parameters/userId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/MemberRoleOrGuest"}}}}}},"responses":{"204":{"description":"User permission was updated"},"404":{"description":"No user found with the given ID","$ref":"#/components/responses/NotFoundError"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/developers/gitbook-api/api-reference/collections/collection-permissions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.