Disable or re-enable an agent in a space
Disable or re-enable an agent in a space.
workflows:write
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.Disable an already admin-disabled agent
The request makes no change and is idempotent.Change an agent blocked by another condition
When the agent has a credit-related pause reason such ascredit_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.
Enable an admin-disabled agent with no other condition
The admin disable is cleared.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.Enable an already active agent
The request makes no change and is idempotent.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 avalidation_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.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
The Admin API version to use for this request.
2026-06-01 Body
"disabled" turns the agent off; "active" re-enables it.
active, disabled Response
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.
active, disabled 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.
active, paused 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.
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