Skip to main content
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

​
page_id
string
required
The ID of the page to update (with or without dashes).
​
properties
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.
​
icon
object | null
Update the page icon. Set to null to remove the icon.
​
cover
object | null
Update the page cover. Set to null to remove the cover.
​
is_locked
boolean
Whether the page should be locked from editing in the Notion app UI.
​
template
object
Apply a template to the page.
​
erase_content
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.
​
archived
boolean
Whether to archive or unarchive the page.
​
in_trash
boolean
Whether to move the page to trash or restore it from trash.
​
auth
string
Bearer token for authentication. Overrides the client-level authentication.

​
Response

​
object
string
Always "page"
​
id
string
The ID of the updated page
​
created_time
string
ISO 8601 timestamp when the page was created
​
last_edited_time
string
ISO 8601 timestamp when the page was last edited (updated after this operation)
​
archived
boolean
Whether the page is archived
​
in_trash
boolean
Whether the page is in trash
​
is_locked
boolean
Whether the page is locked from editing
​
url
string
The URL of the Notion page
​
public_url
string | null
The public URL if published to the web
​
parent
object
Information about the page’s parent
​
properties
object
Updated property values of the page
​
icon
object | null
Page icon
​
cover
object | null
Page cover image
​
created_by
object
User who created the page
​
last_edited_by
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".

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us