> ## 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 an agent in a space > Update an agent's owner, credit source, credit limits, or admin status in one request. The organization bot token must have the following scopes: * `workflows:write` Provide at least one field to update. The API validates the requested changes together and saves them in one transaction. If validation fails, none of the requested changes are saved. ### Ownership and credit limits Changing the owner doesn't clear the agent's editor credit limit. To set a new owner and a new limit together, provide both fields: ```json Request body theme={null} { "owner_user_id": "d71b6edc-0580-4fa3-b7a8-1523e3916bd1", "credit_limit_by_editor": 200 } ``` The new owner must be an eligible workspace member and receives full access to the agent. Omit a credit limit to keep it unchanged. Set it to `null` to remove it. Both limit fields accept non-negative integers. When the agent spends workspace credits, the editor limit can't exceed the workspace admin's limit or the workspace credit limit. These checks use the values after your requested changes. For example, setting the admin limit to `100` and the editor limit to `200` in the same request returns `validation_error` and leaves the agent unchanged. You can't set a workspace admin limit when the agent spends its owner's credits. ### Agent status Use `admin_status` to disable an agent or turn an agent back on after an admin or editor disabled it. This field can't override a Notion-managed pause, such as a credit-limit pause. Credit-limit changes can pause or resume an agent. The API evaluates `admin_status` after applying the other requested fields to the proposed state. ### Response The response has the same agent metadata shape as [List agents in a space](https://developers.notion.com/reference/admin/get-workflows-metadata-for-space.md). It doesn't include the credit limits. Read those with [Get agent credit usage](https://developers.notion.com/reference/admin/get-agent-credit-usage.md). ## OpenAPI ````yaml openapi-adminApi.json PATCH /v1/spaces/{space_id}/agents/{agent_id} 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}: patch: tags: - Admin API summary: Update an agent in a space operationId: update-agent parameters: - $ref: '#/components/parameters/notionVersion' - name: agent_id in: path required: true schema: type: string format: uuid description: The agent to update. - name: space_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object properties: owner_user_id: type: string format: uuid description: >- The new owner: a workspace member who is allowed to own custom agents. The owner gets full access to the agent. The editor credit limit is unchanged unless credit_limit_by_editor is also provided. credit_source: type: string enum: - owner - workspace description: >- Whose credits the agent spends: its owner's ("owner") or the workspace's ("workspace"). "owner" requires the agent to have an owner after this request, either its current owner or owner_user_id in the same request. credit_limit_by_workspace_admin: oneOf: - type: number - type: 'null' description: >- The workspace admin's monthly credit limit for the agent, as a non-negative integer, or null to remove it. Editors can't set credit_limit_by_editor above it. Can't exceed the workspace credit limit, and can't be set when the agent spends its owner's credits (credit_source "owner" after this request). A limit at or below the agent's usage this billing period pauses it; raising or removing the limit resumes an agent paused by it. credit_limit_by_editor: oneOf: - type: number - type: 'null' description: >- The monthly credit limit agent editors set in the agent's settings, as a non-negative integer, or null to remove it. When the agent spends workspace credits, it can't exceed credit_limit_by_workspace_admin (after this request) or the workspace credit limit. A limit at or below the agent's usage this billing period pauses it. admin_status: type: string enum: - active - disabled description: >- "disabled" turns the agent off; "active" turns back on an agent that was disabled by an admin or editor. Agents paused by Notion for another reason, such as a credit limit, can't be disabled or turned back on with this field. Applied after the other fields in the request, which can pause or resume the agent. required: [] additionalProperties: false example: credit_source: workspace credit_limit_by_workspace_admin: 5000 responses: '200': description: '' content: application/json: schema: type: object properties: alive: type: boolean description: >- Whether the agent is live (not soft-deleted). "false" for deleted agents, which are returned only when the "deleted" status filter is set. credit_source: type: string enum: - owner - workspace description: >- Whose credits the agent spends: its owner's ("owner") or the workspace's ("workspace"). id: type: string description: The agent's unique identifier. owner_user_id: oneOf: - type: string format: uuid - type: 'null' description: >- User ID of the member who owns the agent and pays for it when credit_source is "owner"; null when the agent has no owner. space_id: type: string format: uuid status: type: string enum: - active - credit_limit - deleted - disabled_by_notion - disabled_due_to_lack_of_editors - disabled_due_to_lack_of_full_access_members - disabled_from_agent_settings - disabled_from_api - disabled_from_workspace_settings - disabled_from_workspace_settings_but_resumable - failure_limit - internal_error - mark_session_failed_autopause - needs_review - owner_allowance_limit - run_limit - runaway_credit_usage - tool_unavailable - workspace_credit_limit description: >- The agent's current status: "active", "deleted", or a snake_case paused reason. Uses the same values as the status query filter. type: type: string enum: - custom - database_autofill description: Custom agents vs database (autofill) agents. created_by_id: type: string format: uuid created_by_table: type: string enum: - bot - notion_user - organization_bot description: >- The actor table of the agent's creator, such as "notion_user". created_time: type: number description: Epoch ms when the agent was created. description: type: string description: The agent's description. icon: type: string description: The agent's icon. last_credit_usage_time: type: number description: >- Epoch ms of the agent's most recent premium-credit usage; omitted if the agent has never consumed credits. last_edited_by_id: type: string format: uuid last_edited_by_table: type: string enum: - bot - notion_user - organization_bot description: >- The actor table of the agent's last editor, such as "notion_user". last_edited_time: type: number description: Epoch ms when the agent was last edited. last_run_time: type: number description: >- Epoch ms of the agent's most recent run; omitted if the agent has never run. model: type: string description: >- Human-readable model name, such as "Claude 4 Sonnet". Omitted when the agent is set to automatically choose a model, or when no display name is available. modules: type: array items: type: object properties: id: type: string type: type: string name: type: string resources: type: array items: type: object properties: actions: type: array items: type: string description: >- Action verbs granted on these resources (read/write/search/editor/...). ids: type: array items: type: string description: >- Opaque resource identifiers the agent can act on: Slack channel/user URIs, Notion page/collection ids, GitHub repos, Drive file ids, MCP resource URIs, or "*" for workspace-wide access. kind: type: string description: >- Resource discriminator when the module distinguishes kinds (Notion: "pageOrCollectionViewBlock" | "agent" | "workspacePublic" | "databaseProperty"; search: "web" | "helpdocs"; MCP: "tool" | "resource"). Omitted when the module has a single implicit resource kind. additionalProperties: false description: >- A resource, or set of resources, that a module grants the agent access to. This includes the resource kind when available, resource identifiers, and granted actions. description: >- Per-resource access this module grants the agent, such as channels, pages, repositories, files, or MCP resources, and the actions allowed on each. scopes: type: array items: type: string description: >- Distinct capability scopes granted to the module — the action verbs from its permission entries (e.g. Slack "read"/"write", GitHub "search", Notion "reader"/"editor"), aggregated across all resources for a quick overview. version: type: string description: Module version, for change tracking. additionalProperties: false required: - id - type description: >- Summary of a module attached to an agent (which integration + its reach). description: >- The capabilities and tools the agent is allowed to use — both inside Notion and in connected apps such as Slack, the web, or MCP servers. At most 250 module summaries are returned. moved_to_trash_time: type: number description: >- Epoch ms when the agent was deleted; only present for deleted agents. name: type: string description: The agent's name. parent_id: type: string format: uuid parent_table: type: string enum: - block - space description: >- The table the agent is parented to: custom agents belong to the workspace ("space"); database (autofill) agents belong to their database's block ("block"). permissions: type: array items: type: object properties: principal: oneOf: - type: object properties: group_id: type: string format: uuid type: type: string const: group description: Always `group` additionalProperties: false required: - group_id - type - type: object properties: type: type: string const: user description: Always `user` user_id: type: string format: uuid additionalProperties: false required: - type - user_id - type: object properties: type: type: string const: workspace description: Always `workspace` additionalProperties: false required: - type 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. resolved_role: type: string enum: - comment_only - edit - full_access - view_and_interact description: >- The effective role for this principal, including other grants that reach them. A comment-only grant may remain comment-only when no stronger grant applies. role: type: string enum: - comment_only - edit - full_access - view_and_interact description: >- The role stored on this principal's agent permission item. additionalProperties: false required: - principal - resolved_role - role description: >- A principal with its stored and workspace-resolved roles. description: >- Who the agent is shared with: each principal's stored and resolved roles, workspace grant first, at most 250 entries. Omitted for database (autofill) agents, whose sharing state is not exposed. additionalProperties: false required: - alive - credit_source - id - owner_user_id - space_id - status - type '400': description: The request body, path parameters, or query parameters are invalid. content: application/json: schema: $ref: '#/components/schemas/adminApiPublicError400' example: object: 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/adminApiPublicError401' example: object: 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/adminApiPublicError403' example: object: error code: restricted_resource status: 403 message: Forbidden. '404': description: The requested resource could not be found. content: application/json: schema: $ref: '#/components/schemas/adminApiPublicError404' example: object: error code: object_not_found status: 404 message: Not found. '409': description: The request conflicts with the current state of the resource. content: application/json: schema: $ref: '#/components/schemas/adminApiPublicError409' example: object: error code: conflict_error status: 409 message: The request conflicts with the current resource state. '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/adminApiPublicError429' example: object: error code: rate_limited status: 429 message: Rate limited. '500': description: An unexpected server error occurred. content: application/json: schema: $ref: '#/components/schemas/adminApiPublicError500' example: object: error code: internal_server_error status: 500 message: An unexpected error occurred. '503': description: A required service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/adminApiPublicError503' example: object: error code: service_unavailable status: 503 message: Service temporarily unavailable. 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: adminApiPublicError400: type: object properties: object: enum: - error code: enum: - validation_error status: enum: - 400 message: type: string additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string required: - object - code - status - message additionalProperties: false adminApiPublicError401: type: object properties: object: enum: - error code: enum: - unauthorized status: enum: - 401 message: type: string additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string required: - object - code - status - message additionalProperties: false adminApiPublicError403: type: object properties: object: enum: - error code: enum: - restricted_resource status: enum: - 403 message: type: string additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string required: - object - code - status - message additionalProperties: false adminApiPublicError404: type: object properties: object: enum: - error code: enum: - object_not_found status: enum: - 404 message: type: string additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string required: - object - code - status - message additionalProperties: false adminApiPublicError409: type: object properties: object: enum: - error code: enum: - conflict_error status: enum: - 409 message: type: string additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string required: - object - code - status - message additionalProperties: false adminApiPublicError429: type: object properties: object: enum: - error code: enum: - rate_limited status: enum: - 429 message: type: string additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string required: - object - code - status - message additionalProperties: false adminApiPublicError500: type: object properties: object: enum: - error code: enum: - internal_server_error status: enum: - 500 message: type: string additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string required: - object - code - status - message additionalProperties: false adminApiPublicError503: type: object properties: object: enum: - error code: enum: - service_unavailable status: enum: - 503 message: type: string additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string required: - object - code - status - message additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer ````