Skip to main content
PATCH
Update an agent in a space
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:
Request body
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. It doesn’t include the credit limits. Read those with Get agent credit usage.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Notion-Version
enum<string>
required

The Admin API version to use for this request.

Available options:
2026-06-01

Path Parameters

agent_id
string<uuid>
required

The agent to update.

space_id
string<uuid>
required

Body

application/json
owner_user_id
string<uuid>

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
enum<string>

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.

Available options:
owner,
workspace
credit_limit_by_workspace_admin
number | null

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
number | null

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
enum<string>

"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.

Available options:
active,
disabled

Response

alive
boolean
required

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
enum<string>
required

Whose credits the agent spends: its owner's ("owner") or the workspace's ("workspace").

Available options:
owner,
workspace
id
string
required

The agent's unique identifier.

owner_user_id
string<uuid> | null
required

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
string<uuid>
required
status
enum<string>
required

The agent's current status: "active", "deleted", or a snake_case paused reason. Uses the same values as the status query filter.

Available options:
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
type
enum<string>
required

Custom agents vs database (autofill) agents.

Available options:
custom,
database_autofill
created_by_id
string<uuid>
created_by_table
enum<string>

The actor table of the agent's creator, such as "notion_user".

Available options:
bot,
notion_user,
organization_bot
created_time
number

Epoch ms when the agent was created.

description
string

The agent's description.

icon
string

The agent's icon.

last_credit_usage_time
number

Epoch ms of the agent's most recent premium-credit usage; omitted if the agent has never consumed credits.

last_edited_by_id
string<uuid>
last_edited_by_table
enum<string>

The actor table of the agent's last editor, such as "notion_user".

Available options:
bot,
notion_user,
organization_bot
last_edited_time
number

Epoch ms when the agent was last edited.

last_run_time
number

Epoch ms of the agent's most recent run; omitted if the agent has never run.

model
string

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
object[]

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
number

Epoch ms when the agent was deleted; only present for deleted agents.

name
string

The agent's name.

parent_id
string<uuid>
parent_table
enum<string>

The table the agent is parented to: custom agents belong to the workspace ("space"); database (autofill) agents belong to their database's block ("block").

Available options:
block,
space
permissions
object[]

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.