pages.update

Update an existing page’s properties and metadata

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.

Show Property Types

title · array

Array of rich text objects for title properties

rich_text · array

Array of rich text objects for text properties

number · number | null

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

select · object | null

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

multi_select · array

Array of select options (empty array to clear)

date · object | null

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

checkbox · boolean

Boolean value for checkbox properties

url · string | null

URL string (set to null to clear)

email · string | null

Email address string (set to null to clear)

phone_number · string | null

Phone number string (set to null to clear)

people · array

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

files · array

Array of file objects (empty array to clear)

relation · array

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

status · object | null

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

icon · object | null

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

Show Icon Types

emoji · string

A single emoji character

external · object

External file with url property

file_upload · object

File upload with id property

cover · object | null

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

Show Cover Types

external · object

External file with url property

file_upload · object

File upload with id property

is_locked · boolean

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

template · object

Apply a template to the page.

Show Template Types

type · string

One of: default, template_id

template_id · string

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

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

Related Methods

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

See Also

• Notion API: Update page properties
• Working with page properties