Updates a block object by modifying its type-specific content, archival status, or trash status. Not all block types can be updated, and only certain properties are mutable.
Method Signature
client.blocks.update(args: UpdateBlockParameters): Promise<UpdateBlockResponse>
Parameters
The ID of the block to update
The type of block (e.g., "paragraph", "heading_1", "code", etc.). Must match the type-specific content being updated.
Set to true to archive the block, or false to unarchive it
Set to true to move the block to trash, or false to restore it
Optional authentication token to override the client-level auth
Type-Specific Parameters
Depending on the block type, you can update type-specific properties:
For paragraph blocks:
rich_text - Array of rich text objectscolor - Text color (e.g., "blue", "red_background")
For heading 1 blocks:
rich_text - Array of rich text objectscolor - Text coloris_toggleable - Whether the heading can be toggled
For heading 2 blocks (same as heading_1)
For heading 3 blocks (same as heading_1)
For code blocks:
rich_text - Array of rich text objects containing the codelanguage - Programming language (e.g., "javascript", "python")caption - Array of rich text objects for the caption
For to-do blocks:
rich_text - Array of rich text objectschecked - Boolean indicating if the item is checkedcolor - Text color
For callout blocks:
rich_text - Array of rich text objectsicon - Icon object (emoji or file)color - Background color
Response
Returns the updated BlockObjectResponse or PartialBlockObjectResponse.
Updated timestamp reflecting the modification
last_edited_by
PartialUserObjectResponse
User who made the update
Examples
Update Paragraph Text
import { Client } from "@notionhq/client"
const notion = new Client({ auth: process.env.NOTION_TOKEN })
const updatedBlock = await notion.blocks.update({
block_id: "paragraph-block-id",
paragraph: {
rich_text: [
{
type: "text",
text: {
content: "Updated paragraph content",
},
},
],
color: "blue",
},
})
console.log("Block updated:", updatedBlock.last_edited_time)
Update Code Block Language
const codeBlock = await notion.blocks.update({
block_id: "code-block-id",
code: {
rich_text: [
{
type: "text",
text: {
content: "console.log('Hello, World!')",
},
},
],
language: "javascript",
caption: [
{
type: "text",
text: {
content: "Example code",
},
},
],
},
})
Toggle a To-Do Item
const todoBlock = await notion.blocks.update({
block_id: "todo-block-id",
to_do: {
rich_text: [
{
type: "text",
text: {
content: "Complete documentation",
},
},
],
checked: true,
},
})
console.log("To-do checked:", todoBlock.type === "to_do" && todoBlock.to_do.checked)
Archive a Block
// Archive a block without changing its content
const archivedBlock = await notion.blocks.update({
block_id: "your-block-id",
archived: true,
})
console.log("Block archived:", archivedBlock.archived)
Restore from Trash
// Move a block out of trash
const restoredBlock = await notion.blocks.update({
block_id: "your-block-id",
in_trash: false,
})
console.log("Block restored:", !restoredBlock.in_trash)
Update Callout with Icon
const calloutBlock = await notion.blocks.update({
block_id: "callout-block-id",
callout: {
rich_text: [
{
type: "text",
text: {
content: "Important note!",
},
},
],
icon: {
type: "emoji",
emoji: "💡",
},
color: "yellow_background",
},
})
Limitations
Not all block types support all updates. Some restrictions:
- Child pages and child databases cannot have their content updated
- Table blocks cannot be updated after creation
- Some read-only blocks (like breadcrumbs) have limited update capabilities
- You cannot change a block’s type - create a new block instead
Error Handling
import { APIResponseError } from "@notionhq/client"
try {
const block = await notion.blocks.update({
block_id: "your-block-id",
paragraph: {
rich_text: [{ type: "text", text: { content: "New content" } }],
},
})
} catch (error) {
if (APIResponseError.isAPIResponseError(error)) {
switch (error.code) {
case "object_not_found":
console.error("Block not found")
break
case "validation_error":
console.error("Invalid update parameters:", error.message)
break
case "unauthorized":
console.error("Not authorized to update this block")
break
default:
console.error("API error:", error.code, error.message)
}
}
}
Type Safety
The SDK provides full TypeScript support for block updates:
// TypeScript enforces correct structure for each block type
const block = await notion.blocks.update({
block_id: "id",
heading_1: {
rich_text: [{ type: "text", text: { content: "Title" } }],
color: "blue", // Autocomplete for valid colors
is_toggleable: true,
},
})
// Type guard for type-specific properties
if (block.type === "heading_1") {
console.log(block.heading_1.is_toggleable)
}
