apiwatch

All changes / Notion

Deprecation rest

Notion deprecated enhanced markdown (markdown_version v1); the next Notion-Version makes Notion-flavored Markdown (v2) the default and rejects v1 with 400

Took effect · Notion API markdown endpoints (POST /v1/pages, GET and PATCH /v1/pages/:page_id/markdown, POST /v1/comments, PATCH /v1/comments/:comment_id) — markdown_version parameter and enhanced markdown (v1) syntax

Reviewed against the vendor source on Nov 1, 2026 (AI-assisted review). Key facts are re-checked against the source daily.

What changes

On October 30, 2026, Notion deprecated enhanced markdown (v1) on its markdown endpoints (POST /v1/pages, GET and PATCH /v1/pages/:page_id/markdown, POST /v1/comments, PATCH /v1/comments/:comment_id) and told callers to set markdown_version to v2 now and test the results. Nothing changes yet for requests that send a current Notion-Version; they keep v1 as the default and can opt in to v2. The next Notion-Version, whose name and release date are not yet announced, will make Notion-flavored Markdown (v2) the default, so requests without markdown_version get v2 syntax, and requests that set markdown_version to v1 will return a 400 validation_error. Notion plans to retire v1 on every Notion-Version about three months after that version ships and will post the retirement date in the changelog at least three months ahead; no removal date has been given. @notionhq/client v5.29.0 adds markdown_version to the page markdown and comment methods.

Deprecation: Still works; removal is announced.

What to do

Set markdown_version to "v2" on every Notion markdown request now (query parameter on GET /v1/pages/:page_id/markdown; body parameter on PATCH /v1/pages/:page_id/markdown, on POST /v1/pages and the comment endpoints only when the request sends markdown, since sending it with children or rich_text returns a 400 validation_error; @notionhq/client v5.29.0 or later accepts it), then update any code that writes or parses page markdown for the Notion-flavored Markdown syntax (see Notion's Migrate to Notion-flavored Markdown guide) and test the results. Stop sending markdown_version "v1". Before moving to the next Notion-Version, make sure no markdown request still relies on v1.

Strings to search for

markdown_versionretrieveMarkdownupdateMarkdown/markdown

Not affected (matches inside these are ignored): markdown_version: "v2", markdown_version: 'v2', markdown_version="v2", markdown_version='v2', markdown_version": "v2", markdown_version=v2, markdown_version': 'v2', text/markdown

Counts only in files that mention notion + markdown_version or notion + retrieveMarkdown or notion + updateMarkdown or notion + /v1/pages/.

Source

https://developers.notion.com/page/changelog