Update page

Use this API to modify attributes of a Notion page, such as its properties, icon, or cover.

PATCH /v1/pages/{page_id}

TypeScript SDK

JavaScript

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.pages.update({
  page_id: "b55c9c91-384d-452b-81db-d1ef79372b75",
  properties: {
    Name: {
      title: [{ text: { content: "Updated Title" } }]
    }
  }
})

200

{
  "object": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_time": "2023-11-07T05:31:56Z",
  "last_edited_time": "2023-11-07T05:31:56Z",
  "in_trash": true,
  "is_archived": true,
  "is_locked": true,
  "url": "<string>",
  "public_url": "<string>",
  "parent": {
    "type": "<string>",
    "database_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "properties": {},
  "icon": {
    "type": "<string>",
    "emoji": "<string>"
  },
  "cover": {
    "type": "<string>",
    "file": {
      "url": "<string>",
      "expiry_time": "2023-11-07T05:31:56Z"
    }
  },
  "created_by": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "object": "<string>"
  },
  "last_edited_by": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "object": "<string>"
  }
}

Use cases

Updating properties

To change the properties of a page in a data source, use the properties body parameter. This parameter can only be used if the page’s parent is a data source, aside from updating the title of a page outside of a data source.

The page’s properties schema must match the parent data source’s properties.

Setting the icon, cover, or “in trash” status

This endpoint can be used to update any page icon or cover, and can be used to trash or restore any page.

Locking and unlocking a page

Use the is_locked boolean parameter to lock or unlock the page from being further edited in the Notion app UI. Note that this setting doesn’t affect the ability to update the page using the API.

Applying a page template

Use the template body parameter object to apply a template to an existing page. This can either be the parent data source’s default template (type=default), or a specific template (type=template_id).

You can optionally provide template[timezone] — an IANA timezone string (e.g. America/New_York) — to control the timezone used when resolving template variables like @now and @today. If omitted, the associated user’s timezone is used for public connections and personal access tokens, or UTC for internal connections.

After the API request finishes, Notion’s systems merge the content and properties from your chosen template into the current page.

For more information, visit our related guide: Creating pages from templates.

Erasing content from a page

Use the erase_content flag to delete all block children of the current page. Use caution with this parameter, since this is a destructive action that cannot be reversed using the API.

The main use case is for applying a template in scenarios where it makes sense to clear all of the existing page content and replace it with the template page’s content, instead of appending the template content to what’s already on the page.

Adding content to a page

To add content, use the append block children API instead. The page_id can be passed as the block_id when adding block children to the page.

General behavior

Returns the updated page object.

Requirements

Your connection must have update content capabilities on the target page in order to call this endpoint. To update your connection’s capabilities, navigate to the Developer portal, select your connection, open the Configuration tab, and scroll to the Capabilities section.

Attempting a query without update content capabilities returns an HTTP response with a 403 status code.

Limitations

• Updating rollup property values is not supported.
• A page’s parent cannot be changed.

Errors

Each Public API endpoint can return several possible error codes. See the Error codes section of the Status codes documentation for more information.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Notion-Version · enum<string> · required

The API version to use for this request. The latest version is 2026-03-11.

Available options: 2026-03-11

Path Parameters

page_id · string · required

Body

application/json

properties · object

Show child attributes

icon · File Upload · object

File Upload

Emoji

External

Custom Emoji

Icon

Show child attributes

cover · File Upload · object

File Upload

External

Show child attributes

is_locked · boolean

Whether the page should be locked from editing in the Notion app UI. If not provided, the locked state will not be updated.

template · object

Option 1

Option 2

Show child attributes

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.

in_trash · boolean

is_archived · boolean

Response

200

application/json

Option 1

Option 2

object · string · required

The page object type name.

Allowed value: "page"

id · string<uuid> · required

The ID of the page.

created_time · string<date-time> · required

Date and time when this page was created.

last_edited_time · string<date-time> · required

Date and time when this page was last edited.

in_trash · boolean · required

Whether the page is in trash.

is_archived · boolean · required

Whether the page has been archived.

is_locked · boolean · required

Whether the page is locked from editing in the Notion app UI.

url · string · required

The URL of the Notion page.

public_url · string | null · required

The public URL of the Notion page, if it has been published to the web.

parent · object · required

Information about the page's parent.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Show child attributes

properties · object · required

Property values of this page.

Show child attributes

icon · Emoji · object · required

Page icon.

Emoji

File

External

Custom Emoji

Icon

Show child attributes

cover · File · object · required

Page cover image.

File

External

Show child attributes

created_by · object · required

User who created the page.

Show child attributes

last_edited_by · object · required

User who last edited the page.

Show child attributes