Skip to content

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.

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 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.blocks.update_a_block(arguments)
result = await call.wait()
return result.body_json()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
pathobjectRequired within parentAdditional keys: not allowed
path.block_idstringRequired within parent
bodyJSONRequired within parent
body (anyOf 1)JSONAlternative
body (anyOf 1) (anyOf 1)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 1).embedJSONRequired within parent
body (anyOf 1) (anyOf 1).embed (anyOf 1)ModelAlternativeExpand Update a block — request body — body value type bookmark bookmark
body (anyOf 1) (anyOf 1).embed (anyOf 2)ModelAlternativeExpand Update a block — request body — body value type embed embed caption, file upload
body (anyOf 1) (anyOf 1).in_trashbooleanOptional
body (anyOf 1) (anyOf 1).typestringOptionalMust equal: embed
body (anyOf 1) (anyOf 2)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 2).bookmarkModelRequired within parentExpand Update a block — request body — body value type bookmark bookmark
body (anyOf 1) (anyOf 2).in_trashbooleanOptional
body (anyOf 1) (anyOf 2).typestringOptionalMust equal: bookmark
body (anyOf 1) (anyOf 3)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 3).imageModelRequired within parentExpand Update a block — request body — body value type pdf pdf
body (anyOf 1) (anyOf 3).in_trashbooleanOptional
body (anyOf 1) (anyOf 3).typestringOptionalMust equal: image
body (anyOf 1) (anyOf 4)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 4).in_trashbooleanOptional
body (anyOf 1) (anyOf 4).typestringOptionalMust equal: video
body (anyOf 1) (anyOf 4).videoModelRequired within parentExpand Update a block — request body — body value type pdf pdf
body (anyOf 1) (anyOf 5)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 5).in_trashbooleanOptional
body (anyOf 1) (anyOf 5).pdfModelRequired within parentExpand Update a block — request body — body value type pdf pdf
body (anyOf 1) (anyOf 5).typestringOptionalMust equal: pdf
body (anyOf 1) (anyOf 6)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 6).fileModelRequired within parentExpand Update a block — request body — body value type file file
body (anyOf 1) (anyOf 6).in_trashbooleanOptional
body (anyOf 1) (anyOf 6).typestringOptionalMust equal: file
body (anyOf 1) (anyOf 7)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 7).audioModelRequired within parentExpand Update a block — request body — body value type pdf pdf
body (anyOf 1) (anyOf 7).in_trashbooleanOptional
body (anyOf 1) (anyOf 7).typestringOptionalMust equal: audio
body (anyOf 1) (anyOf 8)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 8).codeobjectRequired within parentAdditional keys: not allowed
body (anyOf 1) (anyOf 8).code.captionarrayOptionalMaximum items: 100
body (anyOf 1) (anyOf 8).code.caption[]ModelEach itemExpand Create a database — request body — body title item
body (anyOf 1) (anyOf 8).code.languageModelOptionalExpand Update a block — request body — body value type code code language
body (anyOf 1) (anyOf 8).code.rich_textarrayOptionalMaximum items: 100
body (anyOf 1) (anyOf 8).code.rich_text[]ModelEach itemExpand Create a database — request body — body title item
body (anyOf 1) (anyOf 8).in_trashbooleanOptional
body (anyOf 1) (anyOf 8).typestringOptionalMust equal: code
body (anyOf 1) (anyOf 9)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 9).equationModelRequired within parentExpand Update a block — request body — body value type equation equation
body (anyOf 1) (anyOf 9).in_trashbooleanOptional
body (anyOf 1) (anyOf 9).typestringOptionalMust equal: equation
body (anyOf 1) (anyOf 10)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 10).dividerModelRequired within parentExpand Update a block — request body — body value type tab tab
body (anyOf 1) (anyOf 10).in_trashbooleanOptional
body (anyOf 1) (anyOf 10).typestringOptionalMust equal: divider
body (anyOf 1) (anyOf 11)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 11).breadcrumbModelRequired within parentExpand Update a block — request body — body value type tab tab
body (anyOf 1) (anyOf 11).in_trashbooleanOptional
body (anyOf 1) (anyOf 11).typestringOptionalMust equal: breadcrumb
body (anyOf 1) (anyOf 12)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 12).in_trashbooleanOptional
body (anyOf 1) (anyOf 12).tabModelRequired within parentExpand Update a block — request body — body value type tab tab
body (anyOf 1) (anyOf 12).typestringOptionalMust equal: tab
body (anyOf 1) (anyOf 13)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 13).in_trashbooleanOptional
body (anyOf 1) (anyOf 13).table_of_contentsobjectRequired within parentAdditional keys: not allowed
body (anyOf 1) (anyOf 13).table_of_contents.colorModelOptionalExpand Update a block — request body — body value type quote quote color
body (anyOf 1) (anyOf 13).typestringOptionalMust equal: table_of_contents
body (anyOf 1) (anyOf 14)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 14).in_trashbooleanOptional
body (anyOf 1) (anyOf 14).link_to_pageJSONRequired within parent
body (anyOf 1) (anyOf 14).link_to_page (anyOf 1)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 14).link_to_page (anyOf 1).page_idstringRequired within parent
body (anyOf 1) (anyOf 14).link_to_page (anyOf 1).typestringOptionalMust equal: page_id
body (anyOf 1) (anyOf 14).link_to_page (anyOf 2)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 14).link_to_page (anyOf 2).database_idstringRequired within parent
body (anyOf 1) (anyOf 14).link_to_page (anyOf 2).typestringOptionalMust equal: database_id
body (anyOf 1) (anyOf 14).link_to_page (anyOf 3)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 14).link_to_page (anyOf 3).comment_idstringRequired within parent
body (anyOf 1) (anyOf 14).link_to_page (anyOf 3).typestringOptionalMust equal: comment_id
body (anyOf 1) (anyOf 14).typestringOptionalMust equal: link_to_page
body (anyOf 1) (anyOf 15)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 15).in_trashbooleanOptional
body (anyOf 1) (anyOf 15).table_rowModelRequired within parentExpand Update a block — request body — body value type table row table row
body (anyOf 1) (anyOf 15).typestringOptionalMust equal: table_row
body (anyOf 1) (anyOf 16)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 16).heading_1ModelRequired within parentExpand Update a block — request body — body value type heading 1 heading 1
body (anyOf 1) (anyOf 16).in_trashbooleanOptional
body (anyOf 1) (anyOf 16).typestringOptionalMust equal: heading_1
body (anyOf 1) (anyOf 17)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 17).heading_2ModelRequired within parentExpand Update a block — request body — body value type heading 1 heading 1
body (anyOf 1) (anyOf 17).in_trashbooleanOptional
body (anyOf 1) (anyOf 17).typestringOptionalMust equal: heading_2
body (anyOf 1) (anyOf 18)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 18).heading_3ModelRequired within parentExpand Update a block — request body — body value type heading 1 heading 1
body (anyOf 1) (anyOf 18).in_trashbooleanOptional
body (anyOf 1) (anyOf 18).typestringOptionalMust equal: heading_3
body (anyOf 1) (anyOf 19)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 19).heading_4ModelRequired within parentExpand Update a block — request body — body value type heading 1 heading 1
body (anyOf 1) (anyOf 19).in_trashbooleanOptional
body (anyOf 1) (anyOf 19).typestringOptionalMust equal: heading_4
body (anyOf 1) (anyOf 20)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 20).in_trashbooleanOptional
body (anyOf 1) (anyOf 20).paragraphModelRequired within parentExpand Update a block — request body — body value type paragraph paragraph
body (anyOf 1) (anyOf 20).typestringOptionalMust equal: paragraph
body (anyOf 1) (anyOf 21)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 21).bulleted_list_itemModelRequired within parentExpand Update a block — request body — body value type quote quote
body (anyOf 1) (anyOf 21).in_trashbooleanOptional
body (anyOf 1) (anyOf 21).typestringOptionalMust equal: bulleted_list_item
body (anyOf 1) (anyOf 22)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 22).in_trashbooleanOptional
body (anyOf 1) (anyOf 22).numbered_list_itemModelRequired within parentExpand Update a block — request body — body value type quote quote
body (anyOf 1) (anyOf 22).typestringOptionalMust equal: numbered_list_item
body (anyOf 1) (anyOf 23)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 23).in_trashbooleanOptional
body (anyOf 1) (anyOf 23).quoteModelRequired within parentExpand Update a block — request body — body value type quote quote
body (anyOf 1) (anyOf 23).typestringOptionalMust equal: quote
body (anyOf 1) (anyOf 24)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 24).in_trashbooleanOptional
body (anyOf 1) (anyOf 24).to_doobjectRequired within parent
body (anyOf 1) (anyOf 24).to_do.checkedbooleanOptional
body (anyOf 1) (anyOf 24).to_do.colorModelOptionalExpand Update a block — request body — body value type quote quote color
body (anyOf 1) (anyOf 24).to_do.rich_textarrayOptionalMaximum items: 100
body (anyOf 1) (anyOf 24).to_do.rich_text[]ModelEach itemExpand Create a database — request body — body title item
body (anyOf 1) (anyOf 24).typestringOptionalMust equal: to_do
body (anyOf 1) (anyOf 25)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 25).in_trashbooleanOptional
body (anyOf 1) (anyOf 25).toggleModelRequired within parentExpand Update a block — request body — body value type quote quote
body (anyOf 1) (anyOf 25).typestringOptionalMust equal: toggle
body (anyOf 1) (anyOf 26)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 26).in_trashbooleanOptional
body (anyOf 1) (anyOf 26).templateModelRequired within parentExpand Update a block — request body — body value type template template
body (anyOf 1) (anyOf 26).typestringOptionalMust equal: template
body (anyOf 1) (anyOf 27)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 27).calloutobjectRequired within parent
body (anyOf 1) (anyOf 27).callout.colorModelOptionalExpand Update a block — request body — body value type quote quote color
body (anyOf 1) (anyOf 27).callout.iconModelOptionalExpand Create a database — request body — body icon
body (anyOf 1) (anyOf 27).callout.rich_textarrayOptionalMaximum items: 100
body (anyOf 1) (anyOf 27).callout.rich_text[]ModelEach itemExpand Create a database — request body — body title item
body (anyOf 1) (anyOf 27).in_trashbooleanOptional
body (anyOf 1) (anyOf 27).typestringOptionalMust equal: callout
body (anyOf 1) (anyOf 28)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 28).in_trashbooleanOptional
body (anyOf 1) (anyOf 28).synced_blockobjectRequired within parentAdditional keys: not allowed
body (anyOf 1) (anyOf 28).synced_block.synced_fromobject or nullRequired within parentAdditional keys: not allowed
body (anyOf 1) (anyOf 28).synced_block.synced_from.block_idstringRequired within parent
body (anyOf 1) (anyOf 28).synced_block.synced_from.typestringOptionalMust equal: block_id
body (anyOf 1) (anyOf 28).typestringOptionalMust equal: synced_block
body (anyOf 1) (anyOf 29)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 29).in_trashbooleanOptional
body (anyOf 1) (anyOf 29).tableobjectRequired within parentAdditional keys: not allowed
body (anyOf 1) (anyOf 29).table.has_column_headerbooleanOptional
body (anyOf 1) (anyOf 29).table.has_row_headerbooleanOptional
body (anyOf 1) (anyOf 29).typestringOptionalMust equal: table
body (anyOf 1) (anyOf 30)objectAlternativeAdditional keys: not allowed
body (anyOf 1) (anyOf 30).columnobjectRequired within parentAdditional keys: not allowed
body (anyOf 1) (anyOf 30).column.width_rationumberOptionalRatio 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_trashbooleanOptional
body (anyOf 1) (anyOf 30).typestringOptionalMust equal: column
body (anyOf 2)objectAlternativeAdditional keys: not allowed
body (anyOf 2).in_trashbooleanOptional

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 media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$JSONRoot
$ (anyOf 1)ModelAlternativeExpand Delete a block — response body — object block
$ (anyOf 2)ModelAlternativeExpand Delete a block — response body — value

Referenced models: Delete a block — response body — value, Delete a block — response body — object block

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

Update a block — request body — body value type quote quote color
FieldTypePresenceDescription and constraints
$stringRootOne 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
FieldTypePresenceDescription and constraints
$stringRootOne 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
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
Delete a block — response body — object block
FieldTypePresenceDescription and constraints
$objectRoot
idstringRequired within parentFormat: uuid
objectstringRequired within parentMust equal: block
Update a block — request body — body value type equation equation
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
expressionstringRequired within parent
Update a block — request body — body value type quote quote
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
colorModelOptionalExpand Update a block — request body — body value type quote quote color
rich_textarrayRequired within parentMaximum items: 100
rich_text[]ModelEach itemExpand 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
FieldTypePresenceDescription and constraints
$objectRoot
colorModelOptionalExpand Update a block — request body — body value type quote quote color
iconModelOptionalExpand Create a database — request body — body icon
rich_textarrayOptionalMaximum items: 100
rich_text[]ModelEach itemExpand 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
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
rich_textarrayRequired within parentMaximum items: 100
rich_text[]ModelEach itemExpand 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
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
cellsarrayRequired within parentMaximum items: 100
cells[]arrayEach itemMaximum items: 100
cells[][]ModelEach itemExpand 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
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
colorModelOptionalExpand Update a block — request body — body value type quote quote color
is_toggleablebooleanOptional
rich_textarrayRequired within parentMaximum items: 100
rich_text[]ModelEach itemExpand 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
FieldTypePresenceDescription and constraints
$JSONRoot
$ (oneOf 1)ModelAlternativeExpand Create a database — request body — body icon File Upload
$ (oneOf 2)ModelAlternativeExpand Create a database — request body — body icon Emoji
$ (oneOf 3)ModelAlternativeExpand Create a database — request body — body icon External
$ (oneOf 4)ModelAlternativeExpand Create a database — request body — body icon Custom Emoji
$ (oneOf 5)ModelAlternativeExpand 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
FieldTypePresenceDescription and constraints
$JSONRoot
$ (allOf 1)ModelAll variants applyExpand Create a database — request body — body title item annotations
$ (allOf 2)JSONAll variants apply
$ (allOf 2) (oneOf 1)ModelAlternativeExpand Create a database — request body — body title item value Text
$ (allOf 2) (oneOf 2)ModelAlternativeExpand Create a database — request body — body title item value Mention
$ (allOf 2) (oneOf 3)ModelAlternativeExpand 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
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
captionarrayOptionalMaximum items: 100
caption[]ModelEach itemExpand Create a database — request body — body title item
urlstringOptional

Referenced models: Create a database — request body — body title item

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

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.