Update an agent in a space
Update an agent’s owner, credit source, credit limits, or admin status in one request.
workflows:write
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: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
Useadmin_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. It doesn’t include the credit limits. Read those with Get agent credit usage.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
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.
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.
owner, workspace 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.
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.
"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.
active, disabled Response
Whether the agent is live (not soft-deleted). "false" for deleted agents, which are returned only when the "deleted" status filter is set.
Whose credits the agent spends: its owner's ("owner") or the workspace's ("workspace").
owner, workspace The agent's unique identifier.
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.
The agent's current status: "active", "deleted", or a snake_case paused reason. Uses the same values as the status query filter.
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 Custom agents vs database (autofill) agents.
custom, database_autofill The actor table of the agent's creator, such as "notion_user".
bot, notion_user, organization_bot Epoch ms when the agent was created.
The agent's description.
The agent's icon.
Epoch ms of the agent's most recent premium-credit usage; omitted if the agent has never consumed credits.
The actor table of the agent's last editor, such as "notion_user".
bot, notion_user, organization_bot Epoch ms when the agent was last edited.
Epoch ms of the agent's most recent run; omitted if the agent has never run.
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.
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.
Epoch ms when the agent was deleted; only present for deleted agents.
The agent's name.
The table the agent is parented to: custom agents belong to the workspace ("space"); database (autofill) agents belong to their database's block ("block").
block, space 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.