---
title: "Update a page's content as markdown"
method: PATCH
path: "/v1/pages/{page_id}/markdown"
tags: ["Pages"]
---

# Update a page's content as markdown

`PATCH /v1/pages/{page_id}/markdown`

## Path parameters

- `page_id` string, required

## Headers

- `Notion-Version` '2026-03-11', required

## Request body

- union
  - object
    - `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.
    - `type` 'insert_content', required — Always `insert_content`
    - `insert_content` object, required — Insert new content into the page.
      - `content` string, required — The enhanced markdown content to insert into the page.
      - `after` string — Selection of existing content to insert after, using the ellipsis format ("start text...end text"). Omit to append at the end of the page.
      - `position` union — Explicit position for inserted content. Use {"type":"start"} to prepend or {"type":"end"} to append. Cannot be combined with after.
        - object
          - `type` 'start', required — Insert the content at the start of the page.
        - object
          - `type` 'end', required — Insert the content at the end of the page.
  - object
    - `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.
    - `type` 'replace_content_range', required — Always `replace_content_range`
    - `replace_content_range` object, required — Replace a range of content in the page.
      - `content` string, required — The new enhanced markdown content to replace the matched range.
      - `content_range` string, required — Selection of existing content to replace, using the ellipsis format ("start text...end text").
      - `allow_deleting_content` boolean — Set to true to allow the operation to delete child pages or databases. Defaults to false.
  - object
    - `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.
    - `type` 'update_content', required — Always `update_content`
    - `update_content` object, required — Update specific content using search-and-replace operations.
      - `content_updates` object[], required — An array of search-and-replace operations, each with old_str (content to find) and new_str (replacement content).
        - `old_str` string, required — The existing content string to find and replace. Must exactly match the page content.
        - `new_str` string, required — The new content string to replace old_str with.
        - `replace_all_matches` boolean — If true, replaces all occurrences of old_str. If false (default), the operation fails if there are multiple matches.
      - `allow_deleting_content` boolean — Set to true to allow the operation to delete child pages or databases. Defaults to false.
  - object
    - `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.
    - `type` 'replace_content', required — Always `replace_content`
    - `replace_content` object, required — Replace the entire page content with new markdown.
      - `new_str` string, required — The new enhanced markdown content to replace the entire page content.
      - `allow_deleting_content` boolean — Set to true to allow the operation to delete child pages or databases. Defaults to false.

## Response `200`

- PageMarkdownResponse
  - `object` 'page_markdown', required — The type of object, always 'page_markdown'.
  - `id` string, uuid, required
  - `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` IdResponse[], required — Block IDs that could not be loaded (appeared as <unknown> tags in the markdown). Pass these IDs back to this endpoint to fetch their content separately.

## Other responses

- `202` — Accepted when `allow_async` is true and the update has been queued for background execution.
- `400`
- `401`
- `403`
- `404`
- `406`
- `409`
- `429`
- `500`
- `503`
- `504`
- `529`

---

[API](https://skmtc.net/notion/apis/notion-api.md) · [All operations](https://skmtc.net/notion/apis/notion-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/notion/notion-api/versions/551da43bb186/schema)