Update a Block

Update the content and properties of an existing block

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>

Source: Client.ts:597-608

Parameters

block_id · string · required

The ID of the block to update

type · string

The type of block (e.g., "paragraph", "heading_1", "code", etc.). Must match the type-specific content being updated.

archived · boolean

Set to true to archive the block, or false to unarchive it

in_trash · boolean

Set to true to move the block to trash, or false to restore it

auth · string

Optional authentication token to override the client-level auth

Type-Specific Parameters

Depending on the block type, you can update type-specific properties:

paragraph · object

For paragraph blocks:

• rich_text - Array of rich text objects
• color - Text color (e.g., "blue", "red_background")

heading_1 · object

For heading 1 blocks:

• rich_text - Array of rich text objects
• color - Text color
• is_toggleable - Whether the heading can be toggled

heading_2 · object

For heading 2 blocks (same as heading_1)

heading_3 · object

For heading 3 blocks (same as heading_1)

code · object

For code blocks:

• rich_text - Array of rich text objects containing the code
• language - Programming language (e.g., "javascript", "python")
• caption - Array of rich text objects for the caption

to_do · object

For to-do blocks:

• rich_text - Array of rich text objects
• checked - Boolean indicating if the item is checked
• color - Text color

callout · object

For callout blocks:

• rich_text - Array of rich text objects
• icon - Icon object (emoji or file)
• color - Background color

Response

Returns the updated BlockObjectResponse or PartialBlockObjectResponse.

object · string

Always "block"

id · string

The block ID

type · string

The block type

last_edited_time · string

Updated timestamp reflecting the modification

last_edited_by · PartialUserObjectResponse

User who made the update

archived · boolean

Current archived status

in_trash · boolean

Current trash status

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

Related

• Retrieve a Block
• Delete a Block
• Append Block Children
• Rich Text Reference