> ## 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.
> Disable or re-enable an agent in a space.
# Disable or re-enable an agent in a space
The organization bot token must have the following scopes:
* `workflows:write`
Lets an organization administrator turn an individual agent off, or turn a previously disabled agent back on. Disabling an agent stops its triggers from firing; re-enabling restores normal operation.
Disabling an agent sets its status to `disabled_from_workspace_settings`.
Re-enabling an agent that an administrator disabled restores it to `active`.
### What to expect
#### Disable a running agent
The agent is paused.
```json 200 OK theme={null}
{
"admin_status": "disabled",
"run_status": "paused",
"paused_reason": "disabled_from_workspace_settings"
}
```
#### Disable an already admin-disabled agent
The request makes no change and is idempotent.
```json 200 OK theme={null}
{
"admin_status": "disabled",
"run_status": "paused",
"paused_reason": "disabled_from_workspace_settings"
}
```
#### Change an agent blocked by another condition
When the agent has a credit-related pause reason such as `credit_limit` or `workspace_credit_limit`, or an operational pause reason such as `run_limit`, `failure_limit`, or `tool_unavailable`, either request is rejected with a `validation_error` and leaves the agent unchanged.
```json 400 validation_error theme={null}
{
"type": "error",
"status": 400,
"code": "validation_error",
"message": "…"
}
```
#### Enable an admin-disabled agent with no other condition
The admin disable is cleared.
```json 200 OK theme={null}
{
"admin_status": "active",
"run_status": "active"
}
```
#### Enable an admin-disabled agent when the workspace is over its credit limit
The admin disable is cleared, but the agent remains paused for the workspace credit limit.
```json 200 OK theme={null}
{
"admin_status": "active",
"run_status": "paused",
"paused_reason": "workspace_credit_limit"
}
```
#### Enable an already active agent
The request makes no change and is idempotent.
```json 200 OK theme={null}
{
"admin_status": "active",
"run_status": "active"
}
```
### Important behaviors
**Usage limits are always reflected in the response.** A credit-limit or workspace-credit-limit pause is reported as paused rather than appearing runnable, so the response always reflects whether the agent can actually run. If an agent is currently active but blocked by one of these limits, both disable and enable requests are rejected with a `validation_error` naming the condition, and the agent is left unchanged. If you enable an admin-disabled agent whose workspace is over its credit limit, the admin disable is cleared, but the response reports `run_status: paused` with `paused_reason: workspace_credit_limit` rather than a misleading `active`. Agents whose usage is billed outside Notion credits are exempt from the workspace credit limit and stay active even when the workspace is out of credits.
**Disabling won't replace another pause reason.** If an agent is already paused for a platform or usage reason (for example, a credit limit), an admin disable will not overwrite that reason. Resolve the underlying condition first.
**Workspace policy takes precedence.** If your workspace policy currently disallows custom agents, you cannot re-enable and run an agent — even one that was only admin-disabled.
## OpenAPI
````yaml openapi-adminApi.json PATCH /v1/spaces/{space_id}/agents/{agent_id}/status
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}/status:
patch:
tags:
- Admin API
summary: Disable or re-enable an agent in a space
operationId: update-agent-status
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:
type: object
properties:
admin_status:
description: '"disabled" turns the agent off; "active" re-enables it.'
type: string
enum:
- active
- disabled
required:
- admin_status
example:
admin_status: disabled
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
admin_status:
description: >-
The administrative status you set ("active" or
"disabled"). This is the admin-disable toggle only; it
does not tell you whether the agent will actually run.
type: string
enum:
- active
- disabled
run_status:
description: >-
Whether the agent will actually run right now, independent
of the admin-disable toggle. It reflects the agent's
current state, including usage-based pauses such as a
credit limit or workspace credit limit. It is "active"
only when the agent has no paused reason and will actually
run, and "paused" whenever a 'paused_reason' is present,
whether admin-set or not. Refer to 'paused_reason' for the
reasoning of why an agent is paused.
type: string
enum:
- active
- paused
paused_reason:
description: >-
The authoritative explanation for why an agent is paused
(for example, "disabled_from_workspace_settings" or
"workspace_credit_limit"). It is present only when
'run_status' is "paused", and it is the field you must
inspect to derive the agent's true state.
type: string
enum:
- credit_limit
- 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
- failure_limit
- internal_error
- mark_session_failed_autopause
- needs_review
- run_limit
- runaway_credit_usage
- tool_unavailable
- workspace_credit_limit
required:
- admin_status
- run_status
example:
admin_status: disabled
run_status: paused
paused_reason: disabled_from_workspace_settings
'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
````