Notion: Update a block
Notion blocks.updateABlock: arguments, response, policy and SDK examples.
← Blocks operations · Get started
Operation notion.update_a_block
Provider route: PATCH /v1/blocks/{block_id}. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”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["blocks"]["updateABlock"]>[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.blocks.updateABlock(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom 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.blocks.update_a_block(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
path | object | Required within parent | Additional keys: not allowed |
path.block_id | string | Required within parent | |
body | JSON | Required within parent | |
body (anyOf 1) | JSON | Alternative | |
body (anyOf 1) (anyOf 1) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 1).embed | JSON | Required within parent | |
body (anyOf 1) (anyOf 1).embed (anyOf 1) | Model | Alternative | Expand Update a block — request body — body value type bookmark bookmark |
body (anyOf 1) (anyOf 1).embed (anyOf 2) | Model | Alternative | Expand Update a block — request body — body value type embed embed caption, file upload |
body (anyOf 1) (anyOf 1).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 1).type | string | Optional | Must equal: embed |
body (anyOf 1) (anyOf 2) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 2).bookmark | Model | Required within parent | Expand Update a block — request body — body value type bookmark bookmark |
body (anyOf 1) (anyOf 2).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 2).type | string | Optional | Must equal: bookmark |
body (anyOf 1) (anyOf 3) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 3).image | Model | Required within parent | Expand Update a block — request body — body value type pdf pdf |
body (anyOf 1) (anyOf 3).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 3).type | string | Optional | Must equal: image |
body (anyOf 1) (anyOf 4) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 4).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 4).type | string | Optional | Must equal: video |
body (anyOf 1) (anyOf 4).video | Model | Required within parent | Expand Update a block — request body — body value type pdf pdf |
body (anyOf 1) (anyOf 5) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 5).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 5).pdf | Model | Required within parent | Expand Update a block — request body — body value type pdf pdf |
body (anyOf 1) (anyOf 5).type | string | Optional | Must equal: pdf |
body (anyOf 1) (anyOf 6) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 6).file | Model | Required within parent | Expand Update a block — request body — body value type file file |
body (anyOf 1) (anyOf 6).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 6).type | string | Optional | Must equal: file |
body (anyOf 1) (anyOf 7) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 7).audio | Model | Required within parent | Expand Update a block — request body — body value type pdf pdf |
body (anyOf 1) (anyOf 7).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 7).type | string | Optional | Must equal: audio |
body (anyOf 1) (anyOf 8) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 8).code | object | Required within parent | Additional keys: not allowed |
body (anyOf 1) (anyOf 8).code.caption | array | Optional | Maximum items: 100 |
body (anyOf 1) (anyOf 8).code.caption[] | Model | Each item | Expand Create a database — request body — body title item |
body (anyOf 1) (anyOf 8).code.language | Model | Optional | Expand Update a block — request body — body value type code code language |
body (anyOf 1) (anyOf 8).code.rich_text | array | Optional | Maximum items: 100 |
body (anyOf 1) (anyOf 8).code.rich_text[] | Model | Each item | Expand Create a database — request body — body title item |
body (anyOf 1) (anyOf 8).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 8).type | string | Optional | Must equal: code |
body (anyOf 1) (anyOf 9) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 9).equation | Model | Required within parent | Expand Update a block — request body — body value type equation equation |
body (anyOf 1) (anyOf 9).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 9).type | string | Optional | Must equal: equation |
body (anyOf 1) (anyOf 10) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 10).divider | Model | Required within parent | Expand Update a block — request body — body value type tab tab |
body (anyOf 1) (anyOf 10).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 10).type | string | Optional | Must equal: divider |
body (anyOf 1) (anyOf 11) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 11).breadcrumb | Model | Required within parent | Expand Update a block — request body — body value type tab tab |
body (anyOf 1) (anyOf 11).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 11).type | string | Optional | Must equal: breadcrumb |
body (anyOf 1) (anyOf 12) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 12).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 12).tab | Model | Required within parent | Expand Update a block — request body — body value type tab tab |
body (anyOf 1) (anyOf 12).type | string | Optional | Must equal: tab |
body (anyOf 1) (anyOf 13) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 13).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 13).table_of_contents | object | Required within parent | Additional keys: not allowed |
body (anyOf 1) (anyOf 13).table_of_contents.color | Model | Optional | Expand Update a block — request body — body value type quote quote color |
body (anyOf 1) (anyOf 13).type | string | Optional | Must equal: table_of_contents |
body (anyOf 1) (anyOf 14) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 14).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 14).link_to_page | JSON | Required within parent | |
body (anyOf 1) (anyOf 14).link_to_page (anyOf 1) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 14).link_to_page (anyOf 1).page_id | string | Required within parent | |
body (anyOf 1) (anyOf 14).link_to_page (anyOf 1).type | string | Optional | Must equal: page_id |
body (anyOf 1) (anyOf 14).link_to_page (anyOf 2) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 14).link_to_page (anyOf 2).database_id | string | Required within parent | |
body (anyOf 1) (anyOf 14).link_to_page (anyOf 2).type | string | Optional | Must equal: database_id |
body (anyOf 1) (anyOf 14).link_to_page (anyOf 3) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 14).link_to_page (anyOf 3).comment_id | string | Required within parent | |
body (anyOf 1) (anyOf 14).link_to_page (anyOf 3).type | string | Optional | Must equal: comment_id |
body (anyOf 1) (anyOf 14).type | string | Optional | Must equal: link_to_page |
body (anyOf 1) (anyOf 15) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 15).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 15).table_row | Model | Required within parent | Expand Update a block — request body — body value type table row table row |
body (anyOf 1) (anyOf 15).type | string | Optional | Must equal: table_row |
body (anyOf 1) (anyOf 16) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 16).heading_1 | Model | Required within parent | Expand Update a block — request body — body value type heading 1 heading 1 |
body (anyOf 1) (anyOf 16).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 16).type | string | Optional | Must equal: heading_1 |
body (anyOf 1) (anyOf 17) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 17).heading_2 | Model | Required within parent | Expand Update a block — request body — body value type heading 1 heading 1 |
body (anyOf 1) (anyOf 17).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 17).type | string | Optional | Must equal: heading_2 |
body (anyOf 1) (anyOf 18) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 18).heading_3 | Model | Required within parent | Expand Update a block — request body — body value type heading 1 heading 1 |
body (anyOf 1) (anyOf 18).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 18).type | string | Optional | Must equal: heading_3 |
body (anyOf 1) (anyOf 19) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 19).heading_4 | Model | Required within parent | Expand Update a block — request body — body value type heading 1 heading 1 |
body (anyOf 1) (anyOf 19).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 19).type | string | Optional | Must equal: heading_4 |
body (anyOf 1) (anyOf 20) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 20).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 20).paragraph | Model | Required within parent | Expand Update a block — request body — body value type paragraph paragraph |
body (anyOf 1) (anyOf 20).type | string | Optional | Must equal: paragraph |
body (anyOf 1) (anyOf 21) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 21).bulleted_list_item | Model | Required within parent | Expand Update a block — request body — body value type quote quote |
body (anyOf 1) (anyOf 21).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 21).type | string | Optional | Must equal: bulleted_list_item |
body (anyOf 1) (anyOf 22) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 22).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 22).numbered_list_item | Model | Required within parent | Expand Update a block — request body — body value type quote quote |
body (anyOf 1) (anyOf 22).type | string | Optional | Must equal: numbered_list_item |
body (anyOf 1) (anyOf 23) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 23).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 23).quote | Model | Required within parent | Expand Update a block — request body — body value type quote quote |
body (anyOf 1) (anyOf 23).type | string | Optional | Must equal: quote |
body (anyOf 1) (anyOf 24) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 24).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 24).to_do | object | Required within parent | |
body (anyOf 1) (anyOf 24).to_do.checked | boolean | Optional | |
body (anyOf 1) (anyOf 24).to_do.color | Model | Optional | Expand Update a block — request body — body value type quote quote color |
body (anyOf 1) (anyOf 24).to_do.rich_text | array | Optional | Maximum items: 100 |
body (anyOf 1) (anyOf 24).to_do.rich_text[] | Model | Each item | Expand Create a database — request body — body title item |
body (anyOf 1) (anyOf 24).type | string | Optional | Must equal: to_do |
body (anyOf 1) (anyOf 25) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 25).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 25).toggle | Model | Required within parent | Expand Update a block — request body — body value type quote quote |
body (anyOf 1) (anyOf 25).type | string | Optional | Must equal: toggle |
body (anyOf 1) (anyOf 26) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 26).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 26).template | Model | Required within parent | Expand Update a block — request body — body value type template template |
body (anyOf 1) (anyOf 26).type | string | Optional | Must equal: template |
body (anyOf 1) (anyOf 27) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 27).callout | object | Required within parent | |
body (anyOf 1) (anyOf 27).callout.color | Model | Optional | Expand Update a block — request body — body value type quote quote color |
body (anyOf 1) (anyOf 27).callout.icon | Model | Optional | Expand Create a database — request body — body icon |
body (anyOf 1) (anyOf 27).callout.rich_text | array | Optional | Maximum items: 100 |
body (anyOf 1) (anyOf 27).callout.rich_text[] | Model | Each item | Expand Create a database — request body — body title item |
body (anyOf 1) (anyOf 27).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 27).type | string | Optional | Must equal: callout |
body (anyOf 1) (anyOf 28) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 28).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 28).synced_block | object | Required within parent | Additional keys: not allowed |
body (anyOf 1) (anyOf 28).synced_block.synced_from | object or null | Required within parent | Additional keys: not allowed |
body (anyOf 1) (anyOf 28).synced_block.synced_from.block_id | string | Required within parent | |
body (anyOf 1) (anyOf 28).synced_block.synced_from.type | string | Optional | Must equal: block_id |
body (anyOf 1) (anyOf 28).type | string | Optional | Must equal: synced_block |
body (anyOf 1) (anyOf 29) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 29).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 29).table | object | Required within parent | Additional keys: not allowed |
body (anyOf 1) (anyOf 29).table.has_column_header | boolean | Optional | |
body (anyOf 1) (anyOf 29).table.has_row_header | boolean | Optional | |
body (anyOf 1) (anyOf 29).type | string | Optional | Must equal: table |
body (anyOf 1) (anyOf 30) | object | Alternative | Additional keys: not allowed |
body (anyOf 1) (anyOf 30).column | object | Required within parent | Additional keys: not allowed |
body (anyOf 1) (anyOf 30).column.width_ratio | number | Optional | Ratio between 0 and 1 of the width of this column relative to all columns in the list. If not provided, uses an equal width. Less than: 1 Greater than: 0 |
body (anyOf 1) (anyOf 30).in_trash | boolean | Optional | |
body (anyOf 1) (anyOf 30).type | string | Optional | Must equal: column |
body (anyOf 2) | object | Alternative | Additional keys: not allowed |
body (anyOf 2).in_trash | boolean | Optional |
Referenced models: Update a block — request body — body value type quote quote color, Update a block — request body — body value type code code language, Update a block — request body — body value type tab tab, Update a block — request body — body value type equation equation, Update a block — request body — body value type quote quote, Update a block — request body — body value type paragraph paragraph, Update a block — request body — body value type template template, Update a block — request body — body value type table row table row, Update a block — request body — body value type heading 1 heading 1, Create a database — request body — body icon, Create a database — request body — body title item, Update a block — request body — body value type embed embed caption, file upload, Update a block — request body — body value type pdf pdf, Update a block — request body — body value type file file, Update a block — request body — body value type bookmark bookmark
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | Model | Alternative | Expand Delete a block — response body — object block |
$ (anyOf 2) | Model | Alternative | Expand Delete a block — response body — value |
Referenced models: Delete a block — response body — value, Delete a block — response body — object block
Schemas
Section titled “Schemas”113 more schemas are linked from the tables above, on the schema pages.
Update a block — request body — body value type quote quote color
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | string | Root | One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`, `default_background`, `gray_background`, `brown_background`, `orange_background`, `yellow_background`, `green_background`, `blue_background`, `purple_background`, `pink_background`, `red_background` One of: default, gray, brown, orange, yellow, green, blue, purple, pink, red, default_background, gray_background, brown_background, orange_background, yellow_background, green_background, blue_background, purple_background, pink_background, red_background |
Update a block — request body — body value type code code language
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | string | Root | One of: abap, abc, agda, arduino, ascii art, assembly, bash, basic, bnf, c, c#, c++, clojure, coffeescript, coq, css, dart, dhall, diff, docker, ebnf, elixir, elm, erlang, f#, flow, fortran, gherkin, glsl, go, graphql, groovy, haskell, hcl, html, idris, java, javascript, json, julia, kotlin, latex, less, lisp, livescript, llvm ir, lua, makefile, markdown, markup, matlab, mathematica, mermaid, nix, notion formula, objective-c, ocaml, pascal, perl, php, plain text, powershell, prolog, protobuf, purescript, python, r, racket, reason, ruby, rust, sass, scala, scheme, scss, shell, smalltalk, solidity, sql, swift, toml, typescript, vb.net, verilog, vhdl, visual basic, webassembly, xml, yaml, java/c/c++/c# |
Update a block — request body — body value type tab tab
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
Delete a block — response body — object block
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
id | string | Required within parent | Format: uuid |
object | string | Required within parent | Must equal: block |
Update a block — request body — body value type equation equation
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
expression | string | Required within parent |
Update a block — request body — body value type quote quote
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
color | Model | Optional | Expand Update a block — request body — body value type quote quote color |
rich_text | array | Required within parent | Maximum items: 100 |
rich_text[] | Model | Each item | Expand Create a database — request body — body title item |
Referenced models: Update a block — request body — body value type quote quote color, Create a database — request body — body title item
Update a block — request body — body value type paragraph paragraph
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
color | Model | Optional | Expand Update a block — request body — body value type quote quote color |
icon | Model | Optional | Expand Create a database — request body — body icon |
rich_text | array | Optional | Maximum items: 100 |
rich_text[] | Model | Each item | Expand Create a database — request body — body title item |
Referenced models: Update a block — request body — body value type quote quote color, Create a database — request body — body icon, Create a database — request body — body title item
Update a block — request body — body value type template template
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
rich_text | array | Required within parent | Maximum items: 100 |
rich_text[] | Model | Each item | Expand Create a database — request body — body title item |
Referenced models: Create a database — request body — body title item
Update a block — request body — body value type table row table row
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
cells | array | Required within parent | Maximum items: 100 |
cells[] | array | Each item | Maximum items: 100 |
cells[][] | Model | Each item | Expand Create a database — request body — body title item |
Referenced models: Create a database — request body — body title item
Update a block — request body — body value type heading 1 heading 1
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
color | Model | Optional | Expand Update a block — request body — body value type quote quote color |
is_toggleable | boolean | Optional | |
rich_text | array | Required within parent | Maximum items: 100 |
rich_text[] | Model | Each item | Expand Create a database — request body — body title item |
Referenced models: Update a block — request body — body value type quote quote color, Create a database — request body — body title item
Create a database — request body — body icon
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (oneOf 1) | Model | Alternative | Expand Create a database — request body — body icon File Upload |
$ (oneOf 2) | Model | Alternative | Expand Create a database — request body — body icon Emoji |
$ (oneOf 3) | Model | Alternative | Expand Create a database — request body — body icon External |
$ (oneOf 4) | Model | Alternative | Expand Create a database — request body — body icon Custom Emoji |
$ (oneOf 5) | Model | Alternative | Expand Create a database — request body — body icon Icon |
Referenced models: Create a database — request body — body icon Custom Emoji, Create a database — request body — body icon Emoji, Create a database — request body — body icon External, Create a database — request body — body icon File Upload, Create a database — request body — body icon Icon
Create a database — request body — body title item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (allOf 1) | Model | All variants apply | Expand Create a database — request body — body title item annotations |
$ (allOf 2) | JSON | All variants apply | |
$ (allOf 2) (oneOf 1) | Model | Alternative | Expand Create a database — request body — body title item value Text |
$ (allOf 2) (oneOf 2) | Model | Alternative | Expand Create a database — request body — body title item value Mention |
$ (allOf 2) (oneOf 3) | Model | Alternative | Expand Create a database — request body — body title item value Equation |
Referenced models: Create a database — request body — body title item value Equation, Create a database — request body — body title item value Mention, Create a database — request body — body title item annotations, Create a database — request body — body title item value Text
Update a block — request body — body value type bookmark bookmark
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
caption | array | Optional | Maximum items: 100 |
caption[] | Model | Each item | Expand Create a database — request body — body title item |
url | string | Optional |
Referenced models: Create a database — request body — body title item
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: notion.update_a_block. Catalog operation: update_a_block. 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"}