pages.update

Updates the properties and metadata of an existing page. You can update property values, change the icon and cover, archive the page, or apply a template.

Method Signature

notion.pages.update(args: UpdatePageParameters): Promise<PageObjectResponse | PartialPageObjectResponse>

Parameters

string

required

The ID of the page to update (with or without dashes).

object

Property values to update. Only include properties you want to change.Each property value is keyed by the property name or ID and includes a type field.

Show Property Types

array

Array of rich text objects for title properties

array

Array of rich text objects for text properties

number | null

Numeric value for number properties (set to null to clear)

object | null

Select option with name or id (set to null to clear)

array

Array of select options (empty array to clear)

object | null

Date object with start and optional end and time_zone (set to null to clear)

boolean

Boolean value for checkbox properties

string | null

URL string (set to null to clear)

string | null

Email address string (set to null to clear)

string | null

Phone number string (set to null to clear)

array

Array of user objects with id fields (empty array to clear)

array

Array of file objects (empty array to clear)

array

Array of relation objects with id fields (empty array to clear)

object | null

Status option with name or id (set to null to clear)

object | null

Update the page icon. Set to null to remove the icon.

Show Icon Types

string

A single emoji character

object

External file with url property

object

File upload with id property

object | null

Update the page cover. Set to null to remove the cover.

Show Cover Types

object

External file with url property

object

File upload with id property

boolean

Whether the page should be locked from editing in the Notion app UI.

object

Apply a template to the page.

Show Template Types

string

One of: default, template_id

string

ID of the template to use (when type is template_id)

boolean

Whether to erase all existing content from the page. When used with a template, the template content replaces the existing content. When used without a template, simply clears the page content.

boolean

Whether to archive or unarchive the page.

boolean

Whether to move the page to trash or restore it from trash.

string

Bearer token for authentication. Overrides the client-level authentication.

Response

string

Always "page"

string

The ID of the updated page

string

ISO 8601 timestamp when the page was created

string

ISO 8601 timestamp when the page was last edited (updated after this operation)

boolean

Whether the page is archived

boolean

Whether the page is in trash

boolean

Whether the page is locked from editing

string

The URL of the Notion page

string | null

The public URL if published to the web

object

Information about the page’s parent

object

Updated property values of the page

object | null

Page icon

object | null

Page cover image

object

User who created the page

object

User who last edited the page

Examples

Update a Single Property

const page = await notion.pages.update({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  properties: {
    Status: {
      status: {
        name: "Done",
      },
    },
  },
})

console.log("Updated status to Done")

Update Multiple Properties

const page = await notion.pages.update({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  properties: {
    Status: {
      status: {
        name: "In Progress",
      },
    },
    Priority: {
      select: {
        name: "High",
      },
    },
    "Due Date": {
      date: {
        start: "2026-03-20",
      },
    },
    Completed: {
      checkbox: false,
    },
  },
})

Clear a Property Value

// Clear a select property
const page = await notion.pages.update({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  properties: {
    Status: {
      status: null,
    },
    "Due Date": {
      date: null,
    },
    Tags: {
      multi_select: [],
    },
  },
})

Update Page Icon and Cover

const page = await notion.pages.update({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  icon: {
    emoji: "🎉",
  },
  cover: {
    external: {
      url: "https://images.unsplash.com/photo-1551788964-14609c6c3046",
    },
  },
})

Archive a Page

const page = await notion.pages.update({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  archived: true,
})

console.log("Page archived")

Move to Trash

const page = await notion.pages.update({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  in_trash: true,
})

console.log("Page moved to trash")

Restore from Trash

const page = await notion.pages.update({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  in_trash: false,
})

console.log("Page restored from trash")

Lock a Page

const page = await notion.pages.update({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  is_locked: true,
})

console.log("Page is now locked")

Update with External URL Icon

const page = await notion.pages.update({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  icon: {
    external: {
      url: "https://example.com/icon.png",
    },
  },
})

Remove Icon and Cover

const page = await notion.pages.update({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  icon: null,
  cover: null,
})

console.log("Removed icon and cover")

Batch Update with Error Handling

import { APIResponseError, APIErrorCode } from "@notionhq/client"

const pageIds = [
  "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  "b55c9c91-384d-452b-81db-d1ef79372b75",
  "c66d0c02-495e-563c-92ec-e80f8496c186",
]

for (const pageId of pageIds) {
  try {
    await notion.pages.update({
      page_id: pageId,
      properties: {
        Status: {
          status: {
            name: "Completed",
          },
        },
      },
    })
    console.log(`Updated page ${pageId}`)
  } catch (error) {
    if (APIResponseError.isAPIResponseError(error)) {
      console.error(`Failed to update ${pageId}: ${error.message}`)
    }
  }
}

Important Notes

Only properties that are explicitly included in the properties object will be updated. Other properties remain unchanged.

Setting erase_content to true will permanently delete all blocks in the page. This action cannot be undone.

To rename a page, update the title property. The property name depends on your database schema but is typically "Name" or "Title".

pages.retrieve - Retrieve an existing page
pages.create - Create a new page
pages.move - Move a page to a different location

Client

Blocks

Pages

Databases

Data Sources

Users

Comments

File Uploads

Search & OAuth

Helpers

Errors

Method Signature

Parameters

Response

Examples

Update a Single Property

Update Multiple Properties

Clear a Property Value

Update Page Icon and Cover

Archive a Page

Move to Trash

Restore from Trash

Lock a Page

Update with External URL Icon

Remove Icon and Cover

Batch Update with Error Handling

Important Notes

See Also

​Method Signature

​Parameters

​Response

​Examples

​Update a Single Property

​Update Multiple Properties

​Clear a Property Value

​Update Page Icon and Cover

​Archive a Page

​Move to Trash

​Restore from Trash

​Lock a Page

​Update with External URL Icon

​Remove Icon and Cover

​Batch Update with Error Handling

​Important Notes

​Related Methods

​See Also

Method Signature

Parameters

Response

Examples

Update a Single Property

Update Multiple Properties

Clear a Property Value

Update Page Icon and Cover

Archive a Page

Move to Trash

Restore from Trash

Lock a Page

Update with External URL Icon

Remove Icon and Cover

Batch Update with Error Handling

Important Notes

Related Methods

See Also