Skip to content

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.

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 os
from alter_sdk import App
from 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()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
pathobjectRequired within parentAdditional keys: not allowed
path.page_idstringRequired within parentThe ID of the page to update.
bodyJSONRequired within parent
body (allOf 1)objectAll variants apply
body (allOf 1).allow_asyncbooleanOptionalSet 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_versionstringOptionalThe 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)JSONAll variants apply
body (allOf 2) (oneOf 1)objectAlternative
body (allOf 2) (oneOf 1).insert_contentobjectRequired within parentInsert new content into the page.
body (allOf 2) (oneOf 1).insert_content.afterstringOptionalSelection 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.contentstringRequired within parentThe 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.positionJSONOptionalExplicit 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)objectAlternative
body (allOf 2) (oneOf 1).insert_content.position (oneOf 1).typestringRequired within parentInsert the content at the start of the page.
Must equal: start
body (allOf 2) (oneOf 1).insert_content.position (oneOf 2)objectAlternative
body (allOf 2) (oneOf 1).insert_content.position (oneOf 2).typestringRequired within parentInsert the content at the end of the page.
Must equal: end
body (allOf 2) (oneOf 1).typestringRequired within parentAlways `insert_content`
Must equal: insert_content
body (allOf 2) (oneOf 2)objectAlternative
body (allOf 2) (oneOf 2).replace_content_rangeobjectRequired within parentReplace a range of content in the page.
body (allOf 2) (oneOf 2).replace_content_range.allow_deleting_contentbooleanOptionalSet to true to allow the operation to delete child pages or databases. Defaults to false.
body (allOf 2) (oneOf 2).replace_content_range.contentstringRequired within parentThe 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_rangestringRequired within parentSelection of existing content to replace, using the ellipsis format (“start text…end text”).
body (allOf 2) (oneOf 2).typestringRequired within parentAlways `replace_content_range`
Must equal: replace_content_range
body (allOf 2) (oneOf 3)objectAlternative
body (allOf 2) (oneOf 3).typestringRequired within parentAlways `update_content`
Must equal: update_content
body (allOf 2) (oneOf 3).update_contentobjectRequired within parentUpdate specific content using search-and-replace operations.
body (allOf 2) (oneOf 3).update_content.allow_deleting_contentbooleanOptionalSet to true to allow the operation to delete child pages or databases. Defaults to false.
body (allOf 2) (oneOf 3).update_content.content_updatesarrayRequired within parentAn 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[]objectEach item
body (allOf 2) (oneOf 3).update_content.content_updates[].new_strstringRequired within parentThe new content string to replace old_str with.
body (allOf 2) (oneOf 3).update_content.content_updates[].old_strstringRequired within parentThe 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_matchesbooleanOptionalIf true, replaces all occurrences of old_str. If false (default), the operation fails if there are multiple matches.
body (allOf 2) (oneOf 4)objectAlternative
body (allOf 2) (oneOf 4).replace_contentobjectRequired within parentReplace the entire page content with new markdown.
body (allOf 2) (oneOf 4).replace_content.allow_deleting_contentbooleanOptionalSet to true to allow the operation to delete child pages or databases. Defaults to false.
body (allOf 2) (oneOf 4).replace_content.new_strstringRequired within parentThe 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).typestringRequired within parentAlways `replace_content`
Must equal: replace_content

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$JSONRoot
$ (anyOf 1)ModelAlternativeExpand Retrieve a page as markdown — response body
$ (anyOf 2)objectAlternativeAdditional keys: allowed
$ (anyOf 2).created_timestringRequired within parentFormat: date-time
$ (anyOf 2).idstringRequired within parentMinimum length: 1
$ (anyOf 2).objectstringRequired within parentKnown values: async_task
$ (anyOf 2).operationJSONRequired within parent
$ (anyOf 2).operation (anyOf 1)objectAlternativeAdditional keys: allowed
$ (anyOf 2).operation (anyOf 1).namestringRequired within parentKnown values: PATCH /v1/pages/:page_id/markdown
$ (anyOf 2).operation (anyOf 1).surfacestringRequired within parentKnown values: rest
$ (anyOf 2).operation (anyOf 2)objectAlternativeAdditional keys: allowed
$ (anyOf 2).operation (anyOf 2).namestringRequired within parentKnown values: create_pages
$ (anyOf 2).operation (anyOf 2).surfacestringRequired within parentKnown values: mcp
$ (anyOf 2).poll_after_secondsJSONRequired within parent
$ (anyOf 2).poll_after_seconds (anyOf 1)integerAlternativeMinimum: 0
$ (anyOf 2).poll_after_seconds (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
$ (anyOf 2).statusstringRequired within parentKnown values: queued, running, retrying
$ (anyOf 2).status_urlstringRequired within parentMinimum length: 1

Referenced models: Retrieve a page as markdown — response body

Retrieve a page as markdown — response body
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: allowed
idstringRequired within parentThe ID of the page or block.
Format: uuid
markdownstringRequired within parentThe 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).
objectstringRequired within parentThe type of object, always 'page_markdown'.
Must equal: page_markdown
truncatedbooleanRequired within parentWhether the content was truncated due to exceeding the record count limit.
unknown_block_idsarrayRequired within parentBlock 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[]stringEach itemFormat: uuid
warningsarrayOptionalContent warnings from a synchronous update. Returned only when there is at least one warning.
Maximum items: 100
warnings[]objectEach itemAdditional keys: allowed
warnings[].codestringRequired within parentThe warning category, for example `unsupported_tag` or `no_match`.
warnings[].messagestringRequired within parentWhat the request changed, ignored, or could not match.

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

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.