Notion: Update a page's content as markdown
Notion pages.updatePageMarkdown: arguments, response, policy and SDK examples.
← Pages operations · Get started
Operation notion.update_page_markdown
Provider route: PATCH /v1/pages/{page_id}/markdown. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/notion with npm, or alter-sdk-notion with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { NotionIntegration } from "@alter-ai/notion";
async function execute(input: Parameters<NotionIntegration["pages"]["updatePageMarkdown"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new NotionIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.pages.updatePageMarkdown(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_notion import NotionIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = NotionIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.pages.update_page_markdown(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
path | object | Required within parent | Additional keys: not allowed |
path.page_id | string | Required within parent | The ID of the page to update. |
body | JSON | Required within parent | |
body (allOf 1) | object | All variants apply | |
body (allOf 1).allow_async | boolean | Optional | 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. |
body (allOf 1).markdown_version | string | Optional | The Markdown syntax to use. `v2` is [Notion-flavored Markdown](/guides/data-apis/notion-flavored-markdown) and is recommended. `v1` is enhanced markdown. It’s deprecated. It’s the default on current Notion-Versions. The next Notion-Version rejects `v1` with a `400` `validation_error`. One of: v1, v2 |
body (allOf 2) | JSON | All variants apply | |
body (allOf 2) (oneOf 1) | object | Alternative | |
body (allOf 2) (oneOf 1).insert_content | object | Required within parent | Insert new content into the page. |
body (allOf 2) (oneOf 1).insert_content.after | string | Optional | Selection of existing content to insert after, using the ellipsis format (“start text…end text”). Omit to append at the end of the page. |
body (allOf 2) (oneOf 1).insert_content.content | string | Required within parent | The Markdown content to insert into the page, in the syntax set by `markdown_version`: Notion-flavored Markdown (`v2`, recommended) or enhanced markdown (`v1`, deprecated, the default on current Notion-Versions). |
body (allOf 2) (oneOf 1).insert_content.position | JSON | Optional | Explicit position for inserted content. Use {“type”:“start”} to prepend or {“type”:“end”} to append. Cannot be combined with after. |
body (allOf 2) (oneOf 1).insert_content.position (oneOf 1) | object | Alternative | |
body (allOf 2) (oneOf 1).insert_content.position (oneOf 1).type | string | Required within parent | Insert the content at the start of the page. Must equal: start |
body (allOf 2) (oneOf 1).insert_content.position (oneOf 2) | object | Alternative | |
body (allOf 2) (oneOf 1).insert_content.position (oneOf 2).type | string | Required within parent | Insert the content at the end of the page. Must equal: end |
body (allOf 2) (oneOf 1).type | string | Required within parent | Always `insert_content` Must equal: insert_content |
body (allOf 2) (oneOf 2) | object | Alternative | |
body (allOf 2) (oneOf 2).replace_content_range | object | Required within parent | Replace a range of content in the page. |
body (allOf 2) (oneOf 2).replace_content_range.allow_deleting_content | boolean | Optional | Set to true to allow the operation to delete child pages or databases. Defaults to false. |
body (allOf 2) (oneOf 2).replace_content_range.content | string | Required within parent | The new Markdown content to replace the matched range, in the syntax set by `markdown_version`: Notion-flavored Markdown (`v2`, recommended) or enhanced markdown (`v1`, deprecated, the default on current Notion-Versions). |
body (allOf 2) (oneOf 2).replace_content_range.content_range | string | Required within parent | Selection of existing content to replace, using the ellipsis format (“start text…end text”). |
body (allOf 2) (oneOf 2).type | string | Required within parent | Always `replace_content_range` Must equal: replace_content_range |
body (allOf 2) (oneOf 3) | object | Alternative | |
body (allOf 2) (oneOf 3).type | string | Required within parent | Always `update_content` Must equal: update_content |
body (allOf 2) (oneOf 3).update_content | object | Required within parent | Update specific content using search-and-replace operations. |
body (allOf 2) (oneOf 3).update_content.allow_deleting_content | boolean | Optional | Set to true to allow the operation to delete child pages or databases. Defaults to false. |
body (allOf 2) (oneOf 3).update_content.content_updates | array | Required within parent | An array of search-and-replace operations, each with old_str (content to find) and new_str (replacement content). Operations that match are applied, and each one that matches nothing is reported in “warnings”. The call fails only when no operation that changes content matches. Maximum items: 100 |
body (allOf 2) (oneOf 3).update_content.content_updates[] | object | Each item | |
body (allOf 2) (oneOf 3).update_content.content_updates[].new_str | string | Required within parent | The new content string to replace old_str with. |
body (allOf 2) (oneOf 3).update_content.content_updates[].old_str | string | Required within parent | The existing content string to find and replace. Must exactly match the page content. Minimum length: 1 |
body (allOf 2) (oneOf 3).update_content.content_updates[].replace_all_matches | boolean | Optional | If true, replaces all occurrences of old_str. If false (default), the operation fails if there are multiple matches. |
body (allOf 2) (oneOf 4) | object | Alternative | |
body (allOf 2) (oneOf 4).replace_content | object | Required within parent | Replace the entire page content with new markdown. |
body (allOf 2) (oneOf 4).replace_content.allow_deleting_content | boolean | Optional | Set to true to allow the operation to delete child pages or databases. Defaults to false. |
body (allOf 2) (oneOf 4).replace_content.new_str | string | Required within parent | The new Markdown content to replace the entire page content, in the syntax set by `markdown_version`: Notion-flavored Markdown (`v2`, recommended) or enhanced markdown (`v1`, deprecated, the default on current Notion-Versions). |
body (allOf 2) (oneOf 4).type | string | Required within parent | Always `replace_content` Must equal: replace_content |
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | Model | Alternative | Expand Retrieve a page as markdown — response body |
$ (anyOf 2) | object | Alternative | Additional keys: allowed |
$ (anyOf 2).created_time | string | Required within parent | Format: date-time |
$ (anyOf 2).id | string | Required within parent | Minimum length: 1 |
$ (anyOf 2).object | string | Required within parent | Known values: async_task |
$ (anyOf 2).operation | JSON | Required within parent | |
$ (anyOf 2).operation (anyOf 1) | object | Alternative | Additional keys: allowed |
$ (anyOf 2).operation (anyOf 1).name | string | Required within parent | Known values: PATCH /v1/pages/:page_id/markdown |
$ (anyOf 2).operation (anyOf 1).surface | string | Required within parent | Known values: rest |
$ (anyOf 2).operation (anyOf 2) | object | Alternative | Additional keys: allowed |
$ (anyOf 2).operation (anyOf 2).name | string | Required within parent | Known values: create_pages |
$ (anyOf 2).operation (anyOf 2).surface | string | Required within parent | Known values: mcp |
$ (anyOf 2).poll_after_seconds | JSON | Required within parent | |
$ (anyOf 2).poll_after_seconds (anyOf 1) | integer | Alternative | Minimum: 0 |
$ (anyOf 2).poll_after_seconds (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
$ (anyOf 2).status | string | Required within parent | Known values: queued, running, retrying |
$ (anyOf 2).status_url | string | Required within parent | Minimum length: 1 |
Referenced models: Retrieve a page as markdown — response body
Schemas
Section titled “Schemas”Retrieve a page as markdown — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
id | string | Required within parent | The ID of the page or block. Format: uuid |
markdown | string | Required within parent | The page content as Markdown, in the syntax set by `markdown_version`: Notion-flavored Markdown (`v2`, recommended) or enhanced markdown (`v1`, deprecated, the default on current Notion-Versions). |
object | string | Required within parent | The type of object, always 'page_markdown'. Must equal: page_markdown |
truncated | boolean | Required within parent | Whether the content was truncated due to exceeding the record count limit. |
unknown_block_ids | array | Required within parent | 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. Maximum items: 100 |
unknown_block_ids[] | string | Each item | Format: uuid |
warnings | array | Optional | Content warnings from a synchronous update. Returned only when there is at least one warning. Maximum items: 100 |
warnings[] | object | Each item | Additional keys: allowed |
warnings[].code | string | Required within parent | The warning category, for example `unsupported_tag` or `no_match`. |
warnings[].message | string | Required within parent | What the request changed, ignored, or could not match. |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: notion.update_page_markdown. Catalog operation: update_page_markdown. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Pinned headers: {"Notion-Version": "2026-03-11"}