Update a page's content as markdown

TypeScript SDK

import { Client } from "@notionhq/client"

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

const response = await notion.pages.updateMarkdown({
  page_id: "b55c9c91-384d-452b-81db-d1ef79372b75",
  type: "update_content",
  update_content: {
    content_updates: [
      {
        old_str: "existing text to find",
        new_str: "replacement text"
      }
    ]
  }
})

curl --request PATCH \
  --url https://api.notion.com/v1/pages/{page_id}/markdown \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Notion-Version: <notion-version>' \
  --data '
{
  "type": "<string>",
  "insert_content": {
    "content": "<string>",
    "after": "<string>",
    "position": {
      "type": "<string>"
    }
  },
  "allow_async": true
}
'

import requests

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

payload = {
    "type": "<string>",
    "insert_content": {
        "content": "<string>",
        "after": "<string>",
        "position": { "type": "<string>" }
    },
    "allow_async": 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}/markdown",
  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([
    'type' => '<string>',
    'insert_content' => [
        'content' => '<string>',
        'after' => '<string>',
        'position' => [
                'type' => '<string>'
        ]
    ],
    'allow_async' => 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}/markdown"

	payload := strings.NewReader("{\n  \"type\": \"<string>\",\n  \"insert_content\": {\n    \"content\": \"<string>\",\n    \"after\": \"<string>\",\n    \"position\": {\n      \"type\": \"<string>\"\n    }\n  },\n  \"allow_async\": 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}/markdown")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"<string>\",\n  \"insert_content\": {\n    \"content\": \"<string>\",\n    \"after\": \"<string>\",\n    \"position\": {\n      \"type\": \"<string>\"\n    }\n  },\n  \"allow_async\": true\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"type\": \"<string>\",\n  \"insert_content\": {\n    \"content\": \"<string>\",\n    \"after\": \"<string>\",\n    \"position\": {\n      \"type\": \"<string>\"\n    }\n  },\n  \"allow_async\": true\n}"

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

{
  "object": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "markdown": "<string>",
  "truncated": true,
  "unknown_block_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}

{
  "object": "async_task",
  "id": "<string>",
  "status_url": "<string>",
  "created_time": "2023-11-07T05:31:56Z",
  "poll_after_seconds": 1,
  "operation": {
    "surface": "rest",
    "name": "PATCH /v1/pages/:page_id/markdown"
  }
}

{
  "object": "<unknown>",
  "message": "<string>",
  "status": "<unknown>",
  "additional_data": {}
}

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

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

{
  "object": "<unknown>",
  "message": "<string>",
  "status": "<unknown>",
  "additional_data": {}
}

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

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

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

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

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

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

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

PATCH

pages

{page_id}

markdown

TypeScript SDK

import { Client } from "@notionhq/client"

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

const response = await notion.pages.updateMarkdown({
  page_id: "b55c9c91-384d-452b-81db-d1ef79372b75",
  type: "update_content",
  update_content: {
    content_updates: [
      {
        old_str: "existing text to find",
        new_str: "replacement text"
      }
    ]
  }
})

curl --request PATCH \
  --url https://api.notion.com/v1/pages/{page_id}/markdown \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Notion-Version: <notion-version>' \
  --data '
{
  "type": "<string>",
  "insert_content": {
    "content": "<string>",
    "after": "<string>",
    "position": {
      "type": "<string>"
    }
  },
  "allow_async": true
}
'

import requests

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

payload = {
    "type": "<string>",
    "insert_content": {
        "content": "<string>",
        "after": "<string>",
        "position": { "type": "<string>" }
    },
    "allow_async": 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}/markdown",
  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([
    'type' => '<string>',
    'insert_content' => [
        'content' => '<string>',
        'after' => '<string>',
        'position' => [
                'type' => '<string>'
        ]
    ],
    'allow_async' => 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}/markdown"

	payload := strings.NewReader("{\n  \"type\": \"<string>\",\n  \"insert_content\": {\n    \"content\": \"<string>\",\n    \"after\": \"<string>\",\n    \"position\": {\n      \"type\": \"<string>\"\n    }\n  },\n  \"allow_async\": 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}/markdown")
  .header("Notion-Version", "<notion-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"<string>\",\n  \"insert_content\": {\n    \"content\": \"<string>\",\n    \"after\": \"<string>\",\n    \"position\": {\n      \"type\": \"<string>\"\n    }\n  },\n  \"allow_async\": true\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"type\": \"<string>\",\n  \"insert_content\": {\n    \"content\": \"<string>\",\n    \"after\": \"<string>\",\n    \"position\": {\n      \"type\": \"<string>\"\n    }\n  },\n  \"allow_async\": true\n}"

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

{
  "object": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "markdown": "<string>",
  "truncated": true,
  "unknown_block_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}

{
  "object": "async_task",
  "id": "<string>",
  "status_url": "<string>",
  "created_time": "2023-11-07T05:31:56Z",
  "poll_after_seconds": 1,
  "operation": {
    "surface": "rest",
    "name": "PATCH /v1/pages/:page_id/markdown"
  }
}

{
  "object": "<unknown>",
  "message": "<string>",
  "status": "<unknown>",
  "additional_data": {}
}

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

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

{
  "object": "<unknown>",
  "message": "<string>",
  "status": "<unknown>",
  "additional_data": {}
}

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

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

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

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

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

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

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

Use cases

Updating content with search-and-replace (recommended)

Use the update_content command to make targeted edits using an array of search-and-replace operations. Each operation specifies an old_str to find and a new_str to replace it with. This is the recommended approach for making precise edits without rewriting the full page.

Replacing all page content (recommended)

Use the replace_content command to replace the entire page content with new markdown. Provide the full replacement content in new_str.

Inserting content (legacy)

Use the insert_content command to add new markdown content to a page. Provide position: { "type": "start" } to prepend, position: { "type": "end" } to explicitly append, or omit position to append to the end of the page. You can also provide an after selection to insert at a specific point; after uses an ellipsis-based selection format: "start text...end text".

We recommend using update_content or replace_content instead. The insert_content command is still supported but may be deprecated in a future version.

Replacing a content range (legacy)

Use the replace_content_range command to replace a matched range of existing content with new markdown. The content_range parameter uses the same ellipsis-based selection format as after.

We recommend using update_content instead. The replace_content_range command is still supported but may be deprecated in a future version.

General behavior

Returns a page_markdown object containing the full page content as enhanced markdown after the update, including truncated and unknown_block_ids fields for large pages. Set allow_async: true at the top level of the request body to receive an HTTP 202 response with an async_task object instead of waiting for the markdown update to finish in the original request. This is useful for high block-count markdown updates, especially replace_content requests and large batches of update_content operations. If allow_async is omitted or false, this endpoint keeps its existing synchronous response behavior. allow_async changes response behavior only; it does not change validation, permissions, or which operation runs. See Retrieve an async task and Working with markdown content for polling examples.

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 to call this endpoint without update content capabilities returns an HTTP response with a 403 status code.

Newlines in contentThe content field expects standard markdown with actual newline characters. In JSON, \n is the escape sequence for a newline — for example, "## Heading\n\nParagraph" creates a heading followed by a paragraph.When using cURL, wrap the --data body in single quotes ('...') so that \n is passed through to the JSON parser. Avoid $'...' quoting, which converts \n into a literal newline and produces invalid JSON.Note that the interactive API explorer on this page does not support multiline input. To test with newlines, use cURL, an SDK, or any HTTP client that sends properly encoded JSON.

Protecting child pages and databasesBy default, this endpoint refuses to delete child pages or databases. If an operation would remove them, a validation_error is returned listing the affected items. Set allow_deleting_content to true in the command body (replace_content_range, update_content, or replace_content) to permit deletion.

Errors

Error code	Condition
`validation_error`	The `content_range` or `after` selection does not match any content in the page, or an `old_str` in `update_content` is not found.
`validation_error`	Both `insert_content.after` and `insert_content.position` are provided. Use only one insertion target.
`validation_error`	The operation would delete child pages or databases and `allow_deleting_content` is not `true`.
`validation_error`	An `old_str` in `update_content` matches multiple locations and `replace_all_matches` is not `true`.
`validation_error`	The provided ID is a database or non-page block.
`validation_error`	The target page is a synced page. Synced pages cannot be updated.
`object_not_found`	The page does not exist or the connection does not have access to it.

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

The ID of the page to update.

Body

application/json

Insert Content
Replace Content Range
Update Content
Replace Content

type

string

required

Always insert_content

Allowed value: "insert_content"

insert_content

object

required

Insert new content into the page.

Show child attributes

allow_async

boolean

Set to true to opt into receiving an async_task result when this update operation is accepted for background execution. If omitted or false, the endpoint keeps the existing synchronous response shape.

Response

object

string

required

The type of object, always 'page_markdown'.

Allowed value: "page_markdown"

string<uuid>

required

The ID of the page or block.

markdown

string

required

The page content rendered as enhanced Markdown.

truncated

boolean

required

Whether the content was truncated due to exceeding the record count limit.

unknown_block_ids

string<uuid>[]

required

Block IDs that could not be loaded (appeared as tags in the markdown). Pass these IDs back to this endpoint to fetch their content separately.

Maximum array length: 100

Retrieve a page as markdown

Create a database

⌘I

Notion API

Objects

Endpoints

Webhook events

Update a page's content as markdown

Use cases

Updating content with search-and-replace (recommended)

Replacing all page content (recommended)

Inserting content (legacy)

Replacing a content range (legacy)

General behavior

Errors

Authorizations

Headers

Path Parameters

Body

Response

​Use cases

​Updating content with search-and-replace (recommended)

​Replacing all page content (recommended)

​Inserting content (legacy)

​Replacing a content range (legacy)

​General behavior

​Errors

Authorizations

Headers

Path Parameters

Body

Response

Use cases

Updating content with search-and-replace (recommended)

Replacing all page content (recommended)

Inserting content (legacy)

Replacing a content range (legacy)

General behavior

Errors