Skip to main content
PATCH
/
v1
/
pages
/
{page_id}
Update page properties
curl --request PATCH \
  --url https://api.notion.com/v1/pages/{page_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Notion-Version: <notion-version>' \
  --data '
{
  "properties": {},
  "icon": {
    "file_upload": {
      "id": "<string>"
    },
    "type": "<string>"
  },
  "cover": {
    "file_upload": {
      "id": "<string>"
    },
    "type": "<string>"
  },
  "is_locked": true,
  "template": {
    "type": "default"
  },
  "erase_content": true,
  "archived": true,
  "in_trash": true
}
'
{
  "object": "<unknown>",
  "message": "<string>",
  "code": "invalid_json",
  "status": "<unknown>",
  "additional_data": {}
}

​
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 archive 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). 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.
RequirementsYour integration must have update content capabilities on the target page in order to call this endpoint. To update your integrations capabilities, navigate to the My integrations dashboard, select your integration, go to the Capabilities tab, and update your settings as needed.Attempting a query without update content capabilities returns an HTTP response with a 403 status code.
Limitations

​
Errors

ErrorsEach 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 2025-09-03.

Available options:
2025-09-03

Path Parameters

​
page_id
string
required

Body

application/json
​
properties
object
​
icon
object
​
cover
object
​
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
​
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
​
in_trash
boolean

Response

​
object
any
required
​
message
string
required
​
code
enum<string>
required
Available options:
invalid_json,
invalid_request_url,
invalid_request,
missing_version,
validation_error
​
status
any
required
​
additional_data
object