Update page

TypeScript SDK

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" } }]
    }
  }
})

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": "file_upload"
  },
  "cover": {
    "file_upload": {
      "id": "<string>"
    },
    "type": "file_upload"
  },
  "is_locked": true,
  "template": {
    "type": "default",
    "timezone": "America/New_York"
  },
  "erase_content": true,
  "in_trash": true,
  "is_archived": true
}
'

import requests

url = "https://api.notion.com/v1/pages/{page_id}"

payload = {
    "properties": {},
    "icon": {
        "file_upload": { "id": "<string>" },
        "type": "file_upload"
    },
    "cover": {
        "file_upload": { "id": "<string>" },
        "type": "file_upload"
    },
    "is_locked": True,
    "template": {
        "type": "default",
        "timezone": "America/New_York"
    },
    "erase_content": True,
    "in_trash": True,
    "is_archived": True
}
headers = {
    "Notion-Version": "<notion-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notion.com/v1/pages/{page_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'properties' => [
        
    ],
    'icon' => [
        'file_upload' => [
                'id' => '<string>'
        ],
        'type' => 'file_upload'
    ],
    'cover' => [
        'file_upload' => [
                'id' => '<string>'
        ],
        'type' => 'file_upload'
    ],
    'is_locked' => true,
    'template' => [
        'type' => 'default',
        'timezone' => 'America/New_York'
    ],
    'erase_content' => true,
    'in_trash' => true,
    'is_archived' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Notion-Version: <notion-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/pages/{page_id}"

	payload := strings.NewReader("{\n  \"properties\": {},\n  \"icon\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"file_upload\"\n  },\n  \"cover\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"file_upload\"\n  },\n  \"is_locked\": true,\n  \"template\": {\n    \"type\": \"default\",\n    \"timezone\": \"America/New_York\"\n  },\n  \"erase_content\": true,\n  \"in_trash\": true,\n  \"is_archived\": true\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Notion-Version", "<notion-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.notion.com/v1/pages/{page_id}")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"properties\": {},\n  \"icon\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"file_upload\"\n  },\n  \"cover\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"file_upload\"\n  },\n  \"is_locked\": true,\n  \"template\": {\n    \"type\": \"default\",\n    \"timezone\": \"America/New_York\"\n  },\n  \"erase_content\": true,\n  \"in_trash\": true,\n  \"is_archived\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/pages/{page_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"properties\": {},\n  \"icon\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"file_upload\"\n  },\n  \"cover\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"file_upload\"\n  },\n  \"is_locked\": true,\n  \"template\": {\n    \"type\": \"default\",\n    \"timezone\": \"America/New_York\"\n  },\n  \"erase_content\": true,\n  \"in_trash\": true,\n  \"is_archived\": true\n}"

response = http.request(request)
puts response.read_body

{
  "object": "page",
  "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": "database_id",
    "database_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "properties": {},
  "icon": {
    "type": "emoji",
    "emoji": "😀"
  },
  "cover": {
    "type": "file",
    "file": {
      "url": "<string>",
      "expiry_time": "2023-11-07T05:31:56Z"
    }
  },
  "created_by": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "object": "user"
  },
  "last_edited_by": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "object": "user"
  }
}

{
  "object": "error",
  "message": "<string>",
  "code": "invalid_json",
  "status": 400,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "unauthorized",
  "status": 401,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "restricted_resource",
  "status": 403,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "object_not_found",
  "status": 404,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "row_limit_exceeded",
  "status": 406,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "conflict_error",
  "status": 409,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "rate_limited",
  "status": 429,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "internal_server_error",
  "status": 500,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_unavailable",
  "status": 503,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "gateway_timeout",
  "status": 504,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_overload",
  "status": 529,
  "additional_data": {}
}

PATCH

pages

{page_id}

TypeScript SDK

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" } }]
    }
  }
})

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": "file_upload"
  },
  "cover": {
    "file_upload": {
      "id": "<string>"
    },
    "type": "file_upload"
  },
  "is_locked": true,
  "template": {
    "type": "default",
    "timezone": "America/New_York"
  },
  "erase_content": true,
  "in_trash": true,
  "is_archived": true
}
'

import requests

url = "https://api.notion.com/v1/pages/{page_id}"

payload = {
    "properties": {},
    "icon": {
        "file_upload": { "id": "<string>" },
        "type": "file_upload"
    },
    "cover": {
        "file_upload": { "id": "<string>" },
        "type": "file_upload"
    },
    "is_locked": True,
    "template": {
        "type": "default",
        "timezone": "America/New_York"
    },
    "erase_content": True,
    "in_trash": True,
    "is_archived": True
}
headers = {
    "Notion-Version": "<notion-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notion.com/v1/pages/{page_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'properties' => [
        
    ],
    'icon' => [
        'file_upload' => [
                'id' => '<string>'
        ],
        'type' => 'file_upload'
    ],
    'cover' => [
        'file_upload' => [
                'id' => '<string>'
        ],
        'type' => 'file_upload'
    ],
    'is_locked' => true,
    'template' => [
        'type' => 'default',
        'timezone' => 'America/New_York'
    ],
    'erase_content' => true,
    'in_trash' => true,
    'is_archived' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Notion-Version: <notion-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/pages/{page_id}"

	payload := strings.NewReader("{\n  \"properties\": {},\n  \"icon\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"file_upload\"\n  },\n  \"cover\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"file_upload\"\n  },\n  \"is_locked\": true,\n  \"template\": {\n    \"type\": \"default\",\n    \"timezone\": \"America/New_York\"\n  },\n  \"erase_content\": true,\n  \"in_trash\": true,\n  \"is_archived\": true\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Notion-Version", "<notion-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.notion.com/v1/pages/{page_id}")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"properties\": {},\n  \"icon\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"file_upload\"\n  },\n  \"cover\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"file_upload\"\n  },\n  \"is_locked\": true,\n  \"template\": {\n    \"type\": \"default\",\n    \"timezone\": \"America/New_York\"\n  },\n  \"erase_content\": true,\n  \"in_trash\": true,\n  \"is_archived\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/pages/{page_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"properties\": {},\n  \"icon\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"file_upload\"\n  },\n  \"cover\": {\n    \"file_upload\": {\n      \"id\": \"<string>\"\n    },\n    \"type\": \"file_upload\"\n  },\n  \"is_locked\": true,\n  \"template\": {\n    \"type\": \"default\",\n    \"timezone\": \"America/New_York\"\n  },\n  \"erase_content\": true,\n  \"in_trash\": true,\n  \"is_archived\": true\n}"

response = http.request(request)
puts response.read_body

{
  "object": "page",
  "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": "database_id",
    "database_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "properties": {},
  "icon": {
    "type": "emoji",
    "emoji": "😀"
  },
  "cover": {
    "type": "file",
    "file": {
      "url": "<string>",
      "expiry_time": "2023-11-07T05:31:56Z"
    }
  },
  "created_by": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "object": "user"
  },
  "last_edited_by": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "object": "user"
  }
}

{
  "object": "error",
  "message": "<string>",
  "code": "invalid_json",
  "status": 400,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "unauthorized",
  "status": 401,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "restricted_resource",
  "status": 403,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "object_not_found",
  "status": 404,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "row_limit_exceeded",
  "status": 406,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "conflict_error",
  "status": 409,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "rate_limited",
  "status": 429,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "internal_server_error",
  "status": 500,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_unavailable",
  "status": 503,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "gateway_timeout",
  "status": 504,
  "additional_data": {}
}

{
  "object": "error",
  "message": "<string>",
  "code": "service_overload",
  "status": 529,
  "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. Property names or IDs must match the parent data source’s schema. See Page property values for each type’s input, read-only fields, and clearing rules. Omitted properties keep their values; array values replace the full array.

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

The is_locked boolean controls whether the page can be edited in Notion. It does not affect updates through 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 time zone such as 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.

Control notifications from page writes

Set notifications.mode to silent to skip the notifications Notion sends people about the change:

Page update notifications to people who get updates for the page through Notify me.
Notifications to people the content @mentions.
Notifications to people the change adds to a Person property.

Set it to default, or omit notifications, to use the standard behavior. Some effects of the change happen in either mode:

Database automations that the change triggers still run, including Send notification to actions.
Reminders set by the change still go off at their scheduled time.
Connection webhooks still receive events for the change.
Page history, page activity, and workspace audit logs still record the change.

RequirementsYour 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

Query Parameters

filter_properties

string[]

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.

notifications

object

Controls the notifications Notion sends people about this change. Set mode to "silent" to skip page update notifications, @mention notifications, and notifications to people added to a Person property, or "default" to use the standard behavior. Database automations, reminders, and connection webhooks still work as usual. Page history, page activity, and workspace audit logs still record the change.

Show child attributes

in_trash

boolean

is_archived

boolean

Response

Option 1
Option 2

object

string

required

The page object type name.

Allowed value: "page"

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.

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

Notion API

Objects

Endpoints

Webhook events

Use cases

Updating properties

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

Locking and unlocking a page

Applying a page template

Erasing content from a page

Adding content to a page

General behavior

Control notifications from page writes

Errors

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

​Use cases

​Updating properties

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

​Locking and unlocking a page

​Applying a page template

​Erasing content from a page

​Adding content to a page

​General behavior

​Control notifications from page writes

​Errors

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

Use cases

Updating properties

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

Locking and unlocking a page

Applying a page template

Erasing content from a page

Adding content to a page

General behavior

Control notifications from page writes

Errors