Notion deprecates enhanced markdown and prepares a v2 API default
TL;DR
On October 30, 2026, Notion deprecated enhanced markdown (v1) and announced that its next Notion-Version will default to Notion-flavored Markdown (v2). Current API versions keep their existing default for now; developers can opt into v2 and test today. The new version and retirement dates have not been announced.
- Status
- Coming Soon
- Released
- Plans
- Not specified
What changed
On October 30, Notion announced a future default change for its markdown APIs. Notion-flavored Markdown (v2) will become the default in the next Notion-Version. Enhanced markdown (v1) is now deprecated.
The affected endpoints create pages, retrieve and update page markdown, and create and update comments. On the next API version, leaving out markdown_version will select v2. Explicitly requesting v1 on that version will return a 400 validation_error.
Current Notion-Versions keep v1 as the default for now. You can already opt into v2 by setting markdown_version to v2. This is an upcoming API-version change, not an immediate change to existing requests or the Notion editor.
Why it matters
Teams that export, import, or edit Notion content through an integration should test both the markdown they send and the markdown they receive before changing API versions. The selected syntax applies to the whole request, including parsing input and rendering responses.
Notion has not announced the next version's name or release date. It plans to retire v1 on every Notion-Version about three months after that release and says it will announce the retirement date at least three months ahead. Do not turn that relative plan into a fixed deadline.
What to test first
- Set
markdown_versiontov2as a query parameter when retrieving page markdown. - Set it in the request body when updating page markdown, creating pages with markdown, or creating and updating comments with markdown.
- Test representative content against the official Notion-flavored Markdown reference before upgrading the API version.
- If you use the JavaScript SDK, Notion says
@notionhq/clientv5.29.0 adds the parameter to page-markdown and comment methods.
Markdown content and review state are separate concerns. See the existing Notion MCP suggested-edits update for the tools that propose changes for review.
Frequently asked questions
Will my current Notion API requests immediately switch to v2?
No. Current Notion-Versions still default to v1 for now. The next Notion-Version will default to v2, and you can explicitly request v2 on current versions to test it now.
When will enhanced markdown stop working?
Notion has not announced a retirement date. Its stated plan is roughly three months after the next API version ships, with the retirement date announced at least three months in advance.
Where do I set markdown_version?
Use a query parameter for retrieving page markdown and a body parameter for page creation, page-markdown updates, and comment creation or updates that use markdown. The parameter selects the syntax for the entire request.
Can I request v1 after upgrading to the next Notion-Version?
No. Notion says an explicit v1 request on the next API version will return a 400 validation_error. That does not change the current versions' default today.