API Version 2026-03-11 Released
Notion has released API version 2026-03-11 with three major breaking changes designed to simplify and modernize the API surface. Developers using the Notion API should plan to update their integrations accordingly.
Breaking Changes
Position-based block placement: The Append block children endpoint now uses a position object instead of a flat after string parameter. This enables more flexible block placement options, including start and end positioning, providing developers with greater control over content structure.
Archived field renamed: All endpoints now use in_trash instead of archived in both request parameters and response bodies. The archived field was deprecated in April 2024 and is now fully removed in this version.
Block type renamed: The transcription block type has been renamed to meeting_notes across all block endpoints, reflecting the evolving feature set.
Migration and SDK Support
Most integrations require only simple find-and-replace updates. Notion provides a comprehensive upgrade guide with step-by-step migration instructions.
The official JavaScript/TypeScript SDK has been updated to version v5.12.0, which adds full support for the new API version. Developers can opt in by updating their SDK and setting notionVersion: "2026-03-11" in their configuration.
Additional Improvements in This Release
Notion MCP enhancements: Two new tools are now available for the Notion Model Context Protocol:
notion-create-view— Create new database views with filters, sorts, grouping, and layout-specific settingsnotion-update-view— Update existing view configurations
Markdown content API improvements: The Update page markdown endpoint now supports update_content (for targeted search-and-replace edits) and replace_content (for complete page replacement). These are recommended over older commands for more precise operations.
Template timezone control: Create and Update page endpoints now accept an optional timezone field in the template parameter, allowing template variables like @now and @today to resolve in specific time zones instead of defaulting to UTC.