> ## Documentation Index > Fetch the complete documentation index at: https://developers.notion.com/llms.txt > Use this file to discover all available pages before exploring further. > Update a custom agent's sharing permissions. # Update a custom agent's sharing permissions The organization bot token must have the following scopes: * `workflows:write` ## OpenAPI ````yaml openapi-adminApi.json PATCH /v1/spaces/{space_id}/agents/{agent_id}/permissions openapi: 3.1.0 info: title: Notion Admin API version: 1.0.0 termsOfService: >- https://notion.notion.site/Terms-and-Privacy-28ffdd083dc3473e9c2da6ec011b58ac servers: - url: https://api.notion.com/admin security: - bearerAuth: [] tags: - name: Exports description: Workspace export endpoints - name: Legal holds description: Legal hold endpoints - name: Managed users description: Managed user endpoints paths: /v1/spaces/{space_id}/agents/{agent_id}/permissions: patch: tags: - Admin API summary: Update a custom agent's sharing permissions operationId: update-agent-permissions parameters: - $ref: '#/components/parameters/notionVersion' - name: agent_id in: path required: true schema: type: string format: uuid - name: space_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: description: >- 'set' upserts (grants or updates the level for) each principal; 'remove' revokes access for each principal. A single request may do both, applied atomically — invalid batches write nothing. At most 100 combined 'set' + 'remove' entries per request, and a principal must not appear in both lists. type: object properties: remove: description: Principals to revoke permissions for. type: array items: description: >- A recipient of a permission grant. 'workspace' maps to a space-wide permission granting all workspace members the given role; guests are never covered by it. anyOf: - type: object properties: group_id: type: string format: uuid type: type: string const: group required: - group_id - type - type: object properties: type: type: string const: user user_id: type: string format: uuid required: - type - user_id - type: object properties: type: type: string const: workspace required: - type set: description: Principals to grant permissions to, or update the level for. type: array items: description: >- A single upsert: grant 'principal' the given 'role' (creating or updating it). type: object properties: principal: anyOf: - type: object properties: group_id: type: string format: uuid type: type: string const: group required: - group_id - type - type: object properties: type: type: string const: user user_id: type: string format: uuid required: - type - user_id - type: object properties: type: type: string const: workspace required: - type role: type: string enum: - edit - full_access - view_and_interact required: - principal - role responses: '200': description: '' content: application/json: schema: type: object properties: permissions: description: >- The updated permission list, in the same shape as the read endpoint. This is a pre-commit projection truncated at 250 entries with no cursor; treat the paginated read endpoint as the source of truth. type: array items: description: >- A principal with its stored and workspace-resolved roles. type: object properties: principal: anyOf: - type: object properties: group_id: type: string format: uuid type: type: string const: group required: - group_id - type - type: object properties: type: type: string const: user user_id: type: string format: uuid required: - type - user_id - type: object properties: type: type: string const: workspace required: - type resolved_role: description: >- The effective role for this principal: the most permissive of the stored role and every other grant that reaches the principal — the workspace-wide grant and, for users, any granted group they belong to. Roles rank "view_and_interact" < "edit" < "full_access", so a user whose stored role is "edit" resolves to "full_access" when the workspace-wide grant allows "full_access". Grants that do not reach the principal are excluded: the workspace-wide grant reaches only full workspace members, and group grants reach only workspace members (never page guests or non-members, even if a stale group-member row still exists for them). type: string enum: - edit - full_access - view_and_interact role: description: >- The role stored on this principal's agent permission item. type: string enum: - edit - full_access - view_and_interact required: - principal - resolved_role - role required: - permissions '400': description: The request body, path parameters, or query parameters are invalid. content: application/json: schema: $ref: '#/components/schemas/adminApiError400' example: type: error code: validation_error status: 400 message: The request body is invalid. '401': description: The request is missing a valid bearer token. content: application/json: schema: $ref: '#/components/schemas/adminApiError401' example: type: error code: unauthorized status: 401 message: Unauthorized. '403': description: >- The authenticated bot does not have access to the requested resource or scope. content: application/json: schema: $ref: '#/components/schemas/adminApiError403' example: type: error code: forbidden status: 403 message: Forbidden. '404': description: The requested resource could not be found. content: application/json: schema: $ref: '#/components/schemas/adminApiError404' example: type: error code: not_found status: 404 message: Not found. '429': description: The request was rate limited. headers: retry-after: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: $ref: '#/components/schemas/adminApiError429' example: type: error code: rate_limited status: 429 message: Rate limited. '500': description: An unexpected server error occurred. content: application/json: schema: $ref: '#/components/schemas/adminApiError500' example: type: error code: internal_server_error status: 500 message: An unexpected error occurred. components: parameters: notionVersion: name: Notion-Version in: header required: true schema: enum: - '2026-06-01' description: The Admin API version to use for this request. schemas: adminApiError400: type: object properties: type: enum: - error code: enum: - validation_error status: enum: - 400 message: type: string required: - type - code - status - message additionalProperties: false adminApiError401: type: object properties: type: enum: - error code: enum: - unauthorized status: enum: - 401 message: type: string required: - type - code - status - message additionalProperties: false adminApiError403: type: object properties: type: enum: - error code: enum: - missing_scope - forbidden status: enum: - 403 message: type: string required: - type - code - status - message additionalProperties: false adminApiError404: type: object properties: type: enum: - error code: enum: - not_found status: enum: - 404 message: type: string required: - type - code - status - message additionalProperties: false adminApiError429: type: object properties: type: enum: - error code: enum: - rate_limited status: enum: - 429 message: type: string required: - type - code - status - message additionalProperties: false adminApiError500: type: object properties: type: enum: - error code: enum: - internal_server_error status: enum: - 500 message: type: string required: - type - code - status - message additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer ````