Update an agent

TypeScript SDK

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const agentId = "1f0c7c06-781b-4987-9986-5c8dd3028013"
const response = await notion.request({
  method: "patch",
  path: "agents/" + encodeURIComponent(agentId),
  body: { name: "Weekly report writer", status: "disabled" }
})

curl --request PATCH \
  --url https://api.notion.com/v1/agents/{agent_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Notion-Version: <notion-version>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "is_favorited": true,
  "model": {
    "mode": "auto"
  }
}
'

import requests

url = "https://api.notion.com/v1/agents/{agent_id}"

payload = {
    "name": "<string>",
    "description": "<string>",
    "is_favorited": True,
    "model": { "mode": "auto" }
}
headers = {
    "Notion-Version": "<notion-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notion.com/v1/agents/{agent_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'is_favorited' => true,
    'model' => [
        'mode' => 'auto'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Notion-Version: <notion-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/agents/{agent_id}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"is_favorited\": true,\n  \"model\": {\n    \"mode\": \"auto\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Notion-Version", "<notion-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.notion.com/v1/agents/{agent_id}")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"is_favorited\": true,\n  \"model\": {\n    \"mode\": \"auto\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/agents/{agent_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"is_favorited\": true,\n  \"model\": {\n    \"mode\": \"auto\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "object": "agent",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_type": "notion_ai",
  "name": "<string>",
  "description": "<string>",
  "instructions_page_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "icon": {
    "type": "emoji",
    "emoji": "😀"
  },
  "model": {
    "mode": "auto"
  },
  "connections": [
    {
      "type": "notion",
      "name": "<string>",
      "account": null,
      "permissions": [
        {
          "target": {
            "type": "page",
            "id": "<string>"
          },
          "scopes": [
            "<string>"
          ]
        }
      ]
    }
  ],
  "status": "active",
  "pause_reason": "run_limit",
  "created_by": {
    "object": "user",
    "type": "user",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "version": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "number": 123,
    "published_at": "<string>"
  },
  "agent_version": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "number": 123,
    "published_at": "<string>"
  },
  "has_unpublished_changes": true,
  "last_run_time": "2023-11-07T05:31:56Z",
  "last_run_at": "2023-11-07T05:31:56Z",
  "credit_limit": 1,
  "triggers": [
    {
      "type": "<string>",
      "enabled": true,
      "schedule": {
        "frequency": "<string>",
        "interval": 2,
        "weekdays": [
          "<string>"
        ],
        "monthdays": [
          2
        ],
        "week_numbers": [
          123
        ],
        "hour": 1,
        "minute": 1,
        "timezone": "<string>",
        "start_date": "<string>",
        "end": {
          "type": "date",
          "end_at": "<string>"
        }
      },
      "config": {}
    }
  ],
  "is_favorited": true,
  "created_time": "2023-11-07T05:31:56Z",
  "last_edited_time": "2023-11-07T05:31:56Z",
  "instructions": "<string>"
}

{
  "object": "error",
  "message": "<string>",
  "code": "invalid_json",
  "status": 400,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "unauthorized",
  "status": 401,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "restricted_resource",
  "status": 403,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "object_not_found",
  "status": 404,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "row_limit_exceeded",
  "status": 406,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "conflict_error",
  "status": 409,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "rate_limited",
  "status": 429,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "internal_server_error",
  "status": 500,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_unavailable",
  "status": 503,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "gateway_timeout",
  "status": 504,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_overload",
  "status": 529,
  "additional_data": {}
}

PATCH

agents

{agent_id}

TypeScript SDK

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const agentId = "1f0c7c06-781b-4987-9986-5c8dd3028013"
const response = await notion.request({
  method: "patch",
  path: "agents/" + encodeURIComponent(agentId),
  body: { name: "Weekly report writer", status: "disabled" }
})

curl --request PATCH \
  --url https://api.notion.com/v1/agents/{agent_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Notion-Version: <notion-version>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "is_favorited": true,
  "model": {
    "mode": "auto"
  }
}
'

import requests

url = "https://api.notion.com/v1/agents/{agent_id}"

payload = {
    "name": "<string>",
    "description": "<string>",
    "is_favorited": True,
    "model": { "mode": "auto" }
}
headers = {
    "Notion-Version": "<notion-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notion.com/v1/agents/{agent_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'is_favorited' => true,
    'model' => [
        'mode' => 'auto'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Notion-Version: <notion-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/agents/{agent_id}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"is_favorited\": true,\n  \"model\": {\n    \"mode\": \"auto\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Notion-Version", "<notion-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.notion.com/v1/agents/{agent_id}")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"is_favorited\": true,\n  \"model\": {\n    \"mode\": \"auto\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/agents/{agent_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"is_favorited\": true,\n  \"model\": {\n    \"mode\": \"auto\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "object": "agent",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_type": "notion_ai",
  "name": "<string>",
  "description": "<string>",
  "instructions_page_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "icon": {
    "type": "emoji",
    "emoji": "😀"
  },
  "model": {
    "mode": "auto"
  },
  "connections": [
    {
      "type": "notion",
      "name": "<string>",
      "account": null,
      "permissions": [
        {
          "target": {
            "type": "page",
            "id": "<string>"
          },
          "scopes": [
            "<string>"
          ]
        }
      ]
    }
  ],
  "status": "active",
  "pause_reason": "run_limit",
  "created_by": {
    "object": "user",
    "type": "user",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "version": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "number": 123,
    "published_at": "<string>"
  },
  "agent_version": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "number": 123,
    "published_at": "<string>"
  },
  "has_unpublished_changes": true,
  "last_run_time": "2023-11-07T05:31:56Z",
  "last_run_at": "2023-11-07T05:31:56Z",
  "credit_limit": 1,
  "triggers": [
    {
      "type": "<string>",
      "enabled": true,
      "schedule": {
        "frequency": "<string>",
        "interval": 2,
        "weekdays": [
          "<string>"
        ],
        "monthdays": [
          2
        ],
        "week_numbers": [
          123
        ],
        "hour": 1,
        "minute": 1,
        "timezone": "<string>",
        "start_date": "<string>",
        "end": {
          "type": "date",
          "end_at": "<string>"
        }
      },
      "config": {}
    }
  ],
  "is_favorited": true,
  "created_time": "2023-11-07T05:31:56Z",
  "last_edited_time": "2023-11-07T05:31:56Z",
  "instructions": "<string>"
}

{
  "object": "error",
  "message": "<string>",
  "code": "invalid_json",
  "status": 400,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "unauthorized",
  "status": 401,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "restricted_resource",
  "status": 403,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "object_not_found",
  "status": 404,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "row_limit_exceeded",
  "status": 406,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "conflict_error",
  "status": 409,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "rate_limited",
  "status": 429,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "internal_server_error",
  "status": 500,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_unavailable",
  "status": 503,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "gateway_timeout",
  "status": 504,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_overload",
  "status": 529,
  "additional_data": {}
}

Send only the fields you want to change. Every body field is optional, but the request needs at least one, and an empty body returns a 400 validation_error. A field set to its current value usually changes nothing. The exception is status: sending "disabled" for an agent that’s already disabled, other than through the API, returns a 403 restricted_resource and rejects the whole request. Leave status out when you only want to change other fields. All the fields in one request save together, so either every change applies or none does. The response is the updated agent object, without instructions.

curl --request PATCH "https://api.notion.com/v1/agents/$AGENT_ID" \
  --header "Authorization: Bearer $NOTION_TOKEN" \
  --header "Notion-Version: 2026-03-11" \
  --header "Content-Type: application/json" \
  --data '{"name":"Weekly report writer","status":"disabled"}'

Which fields each agent and token can change

Field	Custom Agent	Personal agent (`notion_ai`)
`name`	Edit access	Yes
`description`	Edit access. Send `""` to clear it.	No
`model`	Edit access	Yes
`status`	Edit access	No
`is_favorited`	Read access, personal access token only	No

A personal access token acts as its user, so its user’s role on the agent decides which fields it can change. A connection needs the Edit selected agents capability and edit access to the agent. Sending a field the token can’t change returns a 403 restricted_resource. The exception is is_favorited: a connection that sends it gets a 400 validation_error, because only a personal access token can change it. For notion_ai, you can change name and model. name sets the token user’s name for their personal agent. Sending any other field returns a 400 validation_error. Only a personal access token can update notion_ai. To change a Custom Agent’s credit limit, use Update an agent credit limit. Sending credit_limit to this endpoint returns a 400 validation_error.

Set the model

Set model to {"mode": "auto"} to let Notion choose, or to {"mode": "pinned", "id": "<model-id>"} to use one model. The model ID has to be one the token’s user can use, or the request returns a 400 validation_error. Changing a Custom Agent’s model also updates its published version.

Enable or disable a Custom Agent

Set status to "disabled" to turn off a running agent, or "active" to turn it back on. You can re-enable an agent only if an editor disabled it, through the API or in agent settings. An agent paused for another reason, such as reaching its credit limit, returns a 403 restricted_resource. So does re-enabling an agent while the workspace doesn’t allow Custom Agents. This replaces Update agent status, which is deprecated.

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 API version to use for this request. The latest version is 2026-03-11.

Available options:

2026-03-11

Path Parameters

agent_id

required

The agent ID (a UUID), or notion_ai for the personal agent. Endpoint-specific restrictions still apply.

Body

application/json

status

enum<string>

Enable or disable the agent. Re-enabling works only for an agent an editor disabled, through the API or in agent settings.

Available options:

active,

disabled

name

string

The agent's display name.

description

string

The custom agent's short description. Use an empty string to clear it.

is_favorited

boolean

Whether the personal-access-token owner has this agent in their favorites.

model

object

The model selection. Use auto to let Notion choose, or pinned with an available public model ID.

Option 1
Option 2

Show child attributes

Response

object

string

required

Always agent

Allowed value: "agent"

required

agent_type

enum<string>

required

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

Available options:

notion_ai,

custom_agent,

autofill_custom_agent,

external

name

string

required

description

string | null

required

instructions_page_id

string<uuid> | null

required

icon

Emoji · object

required

Show child attributes

model

object

required

The model the agent runs on: auto (Notion selects) or a pinned model.

Option 1
Option 2

Show child attributes

connections

object[]

required

Integrations the agent is connected to (Notion, Slack, Discord, MCP servers, and other connectors), each with an account and per-target permissions.

Maximum array length: 100

Show child attributes

status

enum<string>

required

"active" when the agent can run; "disabled" when it is paused (see pause_reason); "deleted" when it has been removed.

Available options:

active,

disabled,

deleted

pause_reason

enum<string> | null

required

Why the agent is paused when status is "disabled" (e.g. "credit_limit", "disabled_from_workspace_settings"); null when active.

Available options:

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

created_by

object | null

required

Show child attributes

version

object | null

required

Show child attributes

agent_version

object | null

required

Show child attributes

has_unpublished_changes

required

Whether the draft has edits not yet in the published version, or "hidden" when the caller lacks edit access to the agent.

last_run_time

required

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

Pattern: ^\d{4}-\d{2}-\d{2}T

last_run_at

required

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

Pattern: ^\d{4}-\d{2}-\d{2}T

credit_limit

required

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

Required range: x >= 0

triggers

object[]

required

The agent's configured triggers, each with a machine type, an enabled flag, and (for recurrence triggers) a structured schedule.

Maximum array length: 100

Show child attributes

is_favorited

boolean | null

required

Whether this agent is in the caller's personal favorites, or null when the caller has no personal favorites scope.

created_time

string<date-time>

Date and time when this agent was created.

last_edited_time

string<date-time>

Date and time when this agent was last edited.

instructions

string | null

The agent's inline instructions when verbose=true, or null when its instructions are stored on a page.

Notion API

Objects

Endpoints

Webhook events

Which fields each agent and token can change

Set the model

Enable or disable a Custom Agent

Authorizations

Headers

Path Parameters

Body

Response

​Which fields each agent and token can change

​Set the model

​Enable or disable a Custom Agent

Authorizations

Headers

Path Parameters

Body

Response

Which fields each agent and token can change

Set the model

Enable or disable a Custom Agent