Skip to content

Notion: Update agent

Notion agents.updateAgent: arguments, response, policy and SDK examples.

← Agents operations · Get started

Operation notion.update_agent

Provider route: PATCH /v1/agents/{agent_id}. Alter supplies the connection’s credentials and routing.

Install @alter-ai/sdk @alter-ai/notion with npm, or alter-sdk-notion with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { NotionIntegration } from "@alter-ai/notion";
async function execute(input: Parameters<NotionIntegration["agents"]["updateAgent"]>[0]) {
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
const provider = new NotionIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
const call = await provider.agents.updateAgent(input);
const result = await call.wait();
return result.bodyJson();
} finally {
await app.close();
}
}
import os
from alter_sdk import App
from alter_sdk_notion import NotionIntegration
async def execute(arguments):
async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
provider = NotionIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
call = await provider.agents.update_agent(arguments)
result = await call.wait()
return result.body_json()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
pathobjectRequired within parentAdditional keys: not allowed
path.agent_idJSONRequired within parentThe agent ID (a UUID), or `notion_ai` for the personal agent. Endpoint-specific restrictions still apply.
path.agent_id (anyOf 1)stringAlternative
path.agent_id (anyOf 2)stringAlternativeAlways `notion_ai`
Must equal: notion_ai
bodyobjectRequired within parentAdditional keys: not allowed
body.descriptionstringOptionalThe custom agent’s short description. Use an empty string to clear it.
body.is_favoritedbooleanOptionalWhether the personal-access-token owner has this agent in their favorites.
body.modelJSONOptionalThe model selection. Use auto to let Notion choose, or pinned with an available public model ID.
body.model (oneOf 1)objectAlternativeAdditional keys: not allowed
body.model (oneOf 1).modestringRequired within parentLet Notion select the model for each run.
Must equal: auto
body.model (oneOf 2)objectAlternativeAdditional keys: not allowed
body.model (oneOf 2).idstringRequired within parentA public model ID, such as `claude-sonnet-5`. It must currently be available to the caller in this workspace.
body.model (oneOf 2).modestringRequired within parentUse the selected model for each run after publishing the agent.
Must equal: pinned
body.namestringOptionalThe agent’s display name.
body.statusstringOptionalEnable or disable the agent. Re-enabling works only for an agent an editor disabled, through the API or in agent settings.
One of: active, disabled

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
agent_typestringRequired within parentWhat kind of agent this is: “notion_ai” is the personal agent; “custom_agent” is a standalone agent you chat with; “autofill_custom_agent” fills a database property; “external” runs through an external provider.
Known values: notion_ai, custom_agent, autofill_custom_agent, external
agent_versionJSONRequired within parent
agent_version (anyOf 1)objectAlternativeAdditional keys: allowed
agent_version (anyOf 1).idstringRequired within parentThe ID of the published artifact.
Format: uuid
agent_version (anyOf 1).numberJSONRequired within parent
agent_version (anyOf 1).number (anyOf 1)numberAlternativeThe version number.
agent_version (anyOf 1).number (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
agent_version (anyOf 1).published_atstringRequired within parentThe ISO 8601 timestamp when this version was published.
agent_version (anyOf 2)nullAlternative
connectionsarrayRequired within parentIntegrations the agent is connected to (Notion, Slack, Discord, MCP servers, and other connectors), each with an account and per-target permissions.
Maximum items: 100
connections[]JSONEach item
connections[] (anyOf 1)ModelAlternativeExpand Get agent — response body — connections item type notion
connections[] (anyOf 2)ModelAlternativeExpand Get agent — response body — connections item type slack
connections[] (anyOf 3)ModelAlternativeExpand Get agent — response body — connections item type discord
connections[] (anyOf 4)ModelAlternativeExpand Get agent — response body — connections item type mcp server
connections[] (anyOf 5)ModelAlternativeExpand Get agent — response body — connections item type custom mcp server
connections[] (anyOf 6)ModelAlternativeExpand Get agent — response body — connections item account, name, permissions, type
created_byJSONRequired within parent
created_by (anyOf 1)objectAlternativeAdditional keys: allowed
created_by (anyOf 1).idstringRequired within parentThe ID of the user that created this agent.
Format: uuid
created_by (anyOf 1).objectstringRequired within parentAlways `user`
Must equal: user
created_by (anyOf 1).typestringRequired within parentAlways `user`
Must equal: user
created_by (anyOf 2)nullAlternative
created_timestringOptionalDate and time when this agent was created.
Format: date-time
credit_limitJSONRequired within parentThe per-agent credit limit that applies to this agent, null when uncapped, or “hidden” when the caller lacks full access to the agent. This is the effective limit computed at runtime, folding in both the agent’s own limit and any workspace-admin default.
credit_limit (anyOf 1)JSONAlternative
credit_limit (anyOf 1) (anyOf 1)integerAlternativeMinimum: 0
credit_limit (anyOf 1) (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
credit_limit (anyOf 2)stringAlternativeAlways `hidden`
Must equal: hidden
credit_limit (anyOf 3)nullAlternative
descriptionJSONRequired within parent
description (anyOf 1)stringAlternative
description (anyOf 2)nullAlternative
has_unpublished_changesJSONRequired within parentWhether the draft has edits not yet in the published version, or “hidden” when the caller lacks edit access to the agent.
has_unpublished_changes (anyOf 1)booleanAlternative
has_unpublished_changes (anyOf 2)stringAlternativeAlways `hidden`
Must equal: hidden
iconJSONRequired within parent
icon (anyOf 1)ModelAlternativeExpand Get agent — response body — icon value
icon (anyOf 2)ModelAlternativeExpand Get agent — response body — icon type custom agent avatar
icon (anyOf 3)nullAlternative
idJSONRequired within parent
id (anyOf 1)stringAlternativeFormat: uuid
id (anyOf 2)stringAlternativeAlways `notion_ai`
Must equal: notion_ai
instructionsJSONOptionalThe agent’s inline instructions when verbose=true, or null when its instructions are stored on a page.
instructions (anyOf 1)stringAlternative
instructions (anyOf 2)nullAlternative
instructions_page_idJSONRequired within parent
instructions_page_id (anyOf 1)stringAlternativeFormat: uuid
instructions_page_id (anyOf 2)nullAlternative
is_favoritedJSONRequired within parentWhether this agent is in the caller’s personal favorites, or null when the caller has no personal favorites scope.
is_favorited (anyOf 1)booleanAlternative
is_favorited (anyOf 2)nullAlternative
last_edited_timestringOptionalDate and time when this agent was last edited.
Format: date-time
last_run_atJSONRequired within parentISO 8601 timestamp of the agent’s most recent run, null if it has never run, or “hidden” when the caller lacks edit access to the agent.
last_run_at (anyOf 1)stringAlternativeFormat: date-time
Pattern: ^\d{4}-\d{2}-\d{2}T
last_run_at (anyOf 2)stringAlternativeAlways `hidden`
Must equal: hidden
last_run_at (anyOf 3)nullAlternative
last_run_timeJSONRequired within parentISO 8601 timestamp of the agent’s most recent run, null if it has never run, or “hidden” when the caller lacks edit access to the agent.
last_run_time (anyOf 1)stringAlternativeFormat: date-time
Pattern: ^\d{4}-\d{2}-\d{2}T
last_run_time (anyOf 2)stringAlternativeAlways `hidden`
Must equal: hidden
last_run_time (anyOf 3)nullAlternative
modelJSONRequired within parentThe model the agent runs on: auto (Notion selects) or a pinned model.
model (anyOf 1)objectAlternativeAdditional keys: allowed
model (anyOf 1).modestringRequired within parentAlways `auto`
Must equal: auto
model (anyOf 2)objectAlternativeAdditional keys: allowed
model (anyOf 2).idJSONRequired within parentThe public model this agent maps to (e.g. “claude-sonnet-5”), or null for a pre-release / early-access model.
model (anyOf 2).id (anyOf 1)stringAlternative
model (anyOf 2).id (anyOf 2)nullAlternative
model (anyOf 2).modestringRequired within parentAlways `pinned`
Must equal: pinned
namestringRequired within parent
objectstringRequired within parentAlways `agent`
Must equal: agent
pause_reasonJSONRequired within parentWhy the agent is paused when status is “disabled” (e.g. “credit_limit”, “disabled_from_workspace_settings”); null when active.
pause_reason (anyOf 1)stringAlternativeOne of: `run_limit`, `credit_limit`, `runaway_credit_usage`, `workspace_credit_limit`, `owner_allowance_limit`, `failure_limit`, `mark_session_failed_autopause`, `disabled_from_workspace_settings`, `disabled_from_workspace_settings_but_resumable`, `disabled_from_api`, `disabled_from_agent_settings`, `disabled_due_to_no_members_with_access`, `disabled_due_to_lack_of_editors`, `disabled_by_notion`, `internal_error`, `needs_user_review`, `tool_unavailable`
Known values: run_limit, credit_limit, runaway_credit_usage, workspace_credit_limit, owner_allowance_limit, failure_limit, mark_session_failed_autopause, disabled_from_workspace_settings, disabled_from_workspace_settings_but_resumable, disabled_from_api, disabled_from_agent_settings, disabled_due_to_no_members_with_access, disabled_due_to_lack_of_editors, disabled_by_notion, internal_error, needs_user_review, tool_unavailable
pause_reason (anyOf 2)nullAlternative
statusstringRequired within parent”active” when the agent can run; “disabled” when it is paused (see pause_reason); “deleted” when it has been removed.
Known values: active, disabled, deleted
triggersarrayRequired within parentThe agent’s configured triggers, each with a machine type, an enabled flag, and (for recurrence triggers) a structured schedule.
Maximum items: 100
triggers[]ModelEach itemExpand Get agent — response body — triggers item
versionJSONRequired within parent
version (anyOf 1)objectAlternativeAdditional keys: allowed
version (anyOf 1).idstringRequired within parentThe ID of the published artifact.
Format: uuid
version (anyOf 1).numberJSONRequired within parent
version (anyOf 1).number (anyOf 1)numberAlternativeThe version number.
version (anyOf 1).number (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
version (anyOf 1).published_atstringRequired within parentThe ISO 8601 timestamp when this version was published.
version (anyOf 2)nullAlternative

Referenced models: Get agent — response body — icon value, Get agent — response body — connections item type slack, Get agent — response body — connections item account, name, permissions, type, Get agent — response body — connections item type discord, Get agent — response body — connections item type mcp server, Get agent — response body — connections item type notion, Get agent — response body — connections item type custom mcp server, Get agent — response body — icon type custom agent avatar, Get agent — response body — triggers item

13 more schemas are linked from the tables above, on the schema pages.

Get agent — response body — icon value
FieldTypePresenceDescription and constraints
$JSONRoot
$ (anyOf 1)ModelAlternativeExpand Get agent — response body — icon value Emoji
$ (anyOf 2)ModelAlternativeExpand Get agent — response body — icon value File
$ (anyOf 3)ModelAlternativeExpand Get agent — response body — icon value External
$ (anyOf 4)ModelAlternativeExpand Get agent — response body — icon value Custom Emoji
$ (anyOf 5)ModelAlternativeExpand Get agent — response body — icon value Icon

Referenced models: Get agent — response body — icon value Custom Emoji, Get agent — response body — icon value Emoji, Get agent — response body — icon value External, Get agent — response body — icon value File, Get agent — response body — icon value Icon

Get agent — response body — connections item type slack
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
accountJSONRequired within parentThe linked Slack workspace, null when none is linked, or "hidden" when the caller lacks edit access to the agent.
account (anyOf 1)objectAlternativeAdditional keys: allowed
account (anyOf 1).team_idstringRequired within parent
account (anyOf 1).typestringRequired within parentAlways `slack_workspace`
Must equal: slack_workspace
account (anyOf 2)stringAlternativeAlways `hidden`
Must equal: hidden
account (anyOf 3)nullAlternative
namestringRequired within parent
permissionsarrayRequired within parentMaximum items: 100
permissions[]ModelEach itemExpand Get agent — response body — connections item type slack permissions item
typestringRequired within parentAlways `slack`
Must equal: slack

Referenced models: Get agent — response body — connections item type slack permissions item

Get agent — response body — connections item account, name, permissions, type
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
accountJSONRequired within parentThe provider-side account identifier, null when none is linked, or "hidden" when the caller lacks edit access to the agent.
account (anyOf 1)stringAlternative
account (anyOf 2)nullAlternative
namestringRequired within parent
permissionsarrayRequired within parentMaximum items: 100
permissions[]objectEach itemAdditional keys: allowed
permissions[].scopesarrayRequired within parentThe scopes granted on this target.
Maximum items: 100
permissions[].scopes[]stringEach item
permissions[].targetobjectRequired within parentAdditional keys: allowed
permissions[].target.idstringRequired within parent
permissions[].target.typestringRequired within parent
typestringRequired within parentThe connector's machine name (e.g. "github", "google_drive").
Known values: asana, box, calendar, computer, confluence, cursor, feedback, files, fs, github, gmail, google_calendar, google_drive, google_drive_oauth, gtm, helpdocs, images, jira, linear, mail, marketplace, memory, microsoft_teams, microsoft_teams_oauth, outlook, salesforce, search, security, sharepoint, sharepoint_oauth, shopify, skills, system, test, web, webhooks, worker, workers
Get agent — response body — connections item type discord
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
accountJSONRequired within parentThe linked Discord server, null when none is linked, or "hidden" when the caller lacks edit access to the agent.
account (anyOf 1)objectAlternativeAdditional keys: allowed
account (anyOf 1).idstringRequired within parent
account (anyOf 1).typestringRequired within parentAlways `discord_server`
Must equal: discord_server
account (anyOf 2)stringAlternativeAlways `hidden`
Must equal: hidden
account (anyOf 3)nullAlternative
namestringRequired within parent
permissionsarrayRequired within parentMaximum items: 100
permissions[]ModelEach itemExpand Get agent — response body — connections item type discord permissions item
typestringRequired within parentAlways `discord`
Must equal: discord

Referenced models: Get agent — response body — connections item type discord permissions item

Get agent — response body — connections item type mcp server
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
accountJSONRequired within parentThe MCP server host, null when none is linked, or "hidden" when the caller lacks edit access to the agent.
account (anyOf 1)objectAlternativeAdditional keys: allowed
account (anyOf 1).server_hoststringRequired within parentThe MCP server host (never the full URL, which can carry credentials or private path components).
account (anyOf 1).typestringRequired within parentAlways `mcp_server`
Must equal: mcp_server
account (anyOf 2)stringAlternativeAlways `hidden`
Must equal: hidden
account (anyOf 3)nullAlternative
enabled_toolsJSONRequired within parentThe tools the agent may call, null when all tools are enabled (including any the server adds later), or "hidden" when the caller lacks edit access to the agent.
enabled_tools (anyOf 1)arrayAlternativeMaximum items: 100
enabled_tools (anyOf 1)[]objectEach itemAdditional keys: allowed
enabled_tools (anyOf 1)[].namestringRequired within parent
enabled_tools (anyOf 1)[].titleJSONRequired within parent
enabled_tools (anyOf 1)[].title (anyOf 1)stringAlternative
enabled_tools (anyOf 1)[].title (anyOf 2)nullAlternative
enabled_tools (anyOf 2)stringAlternativeAlways `hidden`
Must equal: hidden
enabled_tools (anyOf 3)nullAlternative
namestringRequired within parent
run_tools_automaticallyobjectRequired within parentWhether read / write tool calls run without a confirmation step.
Additional keys: allowed
run_tools_automatically.readbooleanRequired within parentWhether read tool calls run without a confirmation step.
run_tools_automatically.writebooleanRequired within parentWhether write tool calls run without a confirmation step.
typestringRequired within parentAlways `mcp_server`
Must equal: mcp_server
Get agent — response body — connections item type notion
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
accountnullRequired within parent
namestringRequired within parent
permissionsarrayRequired within parentMaximum items: 100
permissions[]ModelEach itemExpand Get agent — response body — connections item type notion permissions item
typestringRequired within parentAlways `notion`
Must equal: notion

Referenced models: Get agent — response body — connections item type notion permissions item

Get agent — response body — icon type custom agent avatar
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
custom_agent_avatarobjectRequired within parentThe static and animated URLs for the agent avatar.
Additional keys: allowed
custom_agent_avatar.animated_urlstringRequired within parentThe URL of the animated custom agent avatar.
custom_agent_avatar.static_urlstringRequired within parentThe URL of the static custom agent avatar.
typestringRequired within parentType of icon. In this case, a custom agent avatar.
Must equal: custom_agent_avatar
Get agent — response body — triggers item
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
configobjectOptionalRemaining per-type trigger configuration (e.g. watched channel ids, reaction config), keys in snake_case. Present only when the trigger carries such state.
Additional keys: see wildcard field
config.*JSONAdditional keys
enabledbooleanRequired within parentWhether this trigger is currently enabled.
scheduleModelOptionalExpand Get agent — response body — triggers item schedule
typestringRequired within parentMachine trigger type (e.g. "notion.agent.mentioned", "recurrence", "slack.reaction.added").

Referenced models: Get agent — response body — triggers item schedule

SDK function policy ID: notion.update_agent. Catalog operation: update_agent. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Notion-Version": "2026-03-11"}

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.