Notion Developers Release Notes

Heading 4 block type is now a supported block type

You can create, read, and update heading 4 blocks through the Append block children, Retrieve a block, and Update a block endpoints, matching the existing heading_1, heading_2, and heading_3 block types.

Tab item icons

Paragraph blocks that are direct children of tab blocks now support an optional icon field. You can set icons on tab items when creating tabs via Append block children or Create a page, and update them via Update a block. Icons on paragraphs that are not tab items are rejected with a validation error.

”me” relative filter for people properties

People filter conditions now accept "me" as a value for contains and does_not_contain, in addition to user UUIDs. For public integrations, "me" resolves to the user who authorized the connection. For internal integrations, "me" does not resolve to a user — a contains: "me" filter will return no results and a does_not_contain: "me" filter will match all entries. Works across database queries, data source queries, view filters, and quick filters.

Relative date filter values

Date filter conditions that accept an ISO 8601 date string (equals, before, after, on_or_before, on_or_after) now also accept the following relative date values: "today", "tomorrow", "yesterday", "one_week_ago", "one_week_from_now", "one_month_ago", "one_month_from_now". These are resolved at query time relative to the current date. See the date filter reference for details.

View API fixes

Several fixes to the views API:

• Percent-encoded property IDs: Property IDs returned by the API (e.g. %7DUlu) are now correctly resolved when used in view filters, sorts, group-by, and other property references.
• width: 0 rejected: Column widths must now be at least 1. A width of 0 was previously accepted but had no effect.
• Partial properties list: Specifying a subset of properties in a view now correctly hides unlisted properties instead of showing all properties.

SDK support: @notionhq/client v5.16.0 includes typed support for heading 4, tab item icons, and the "me" person filter value.

Tab block support

Tab blocks are now a supported block type in the API. Use tabs to organize content into labeled sections within a page.

• Read: Retrieve a block and Retrieve block children return tab blocks with type: "tab" and an empty tab: {} object. Each tab within the container is a paragraph block — the rich_text is the tab label, the icon is the tab icon, and the children contain the tab’s content.
• Create: Append block children accepts type: "tab" blocks. Each tab is a paragraph block with nested children and an optional icon. Only paragraph blocks can be direct children of a tab block.

Writable verification property

The verification property on wiki database pages can now be set and updated via the Create page and Update page endpoints. Set state to "verified" or "unverified", with an optional date object for expiration. The verified_by field is automatically set to the acting integration and cannot be overridden.

Native icons and custom emoji listing

Two icon-related improvements:

• Native Notion icons: A new type: "icon" variant is available on all icon fields (pages, databases, callout blocks). Specify an icon by name and optional color (defaults to "gray"). Previously, native icons were returned as type: "external" with SVG URLs — they are now returned in the structured icon format.
• Custom emoji listing: A new List custom emojis endpoint (GET /v1/custom_emojis) retrieves workspace custom emojis with cursor pagination and an optional name filter for exact-match lookups.

SDK support: @notionhq/client v5.15.0 adds notion.customEmojis.list() and typed support for tab blocks, verification writes, and native icons.

Views API

We’ve launched the /v1/views API. Eight new endpoints let integrations programmatically manage database views — the same view presets that users create in the Notion UI:

• Create, retrieve, update, and delete views on any database.
• List views for a database or across the workspace by data source.
• Query a view to fetch pages using the view’s saved filter and sort configuration, with pagination support.

Supported view types include table, board, calendar, timeline, gallery, list, form, chart, map, and dashboard. Views can be configured with filters, sorts, and type-specific layout settings like grouping, cover images, subtasks, and chart options.

Dashboard views support a full grid layout with widget placement — add, position, and remove widget views within rows.

Three new webhook events (view.created, view.updated, view.deleted) are available on API version 2025-09-03 and later.

SDK support: @notionhq/client v5.14.0 adds notion.views.* and notion.views.queries.* methods.

New API version: 2026-03-11

We’ve released Notion API version 2026-03-11 with three breaking changes that simplify and modernize the API surface:

• after replaced by position: The Append block children endpoint now uses a position object instead of a flat after string parameter, enabling more flexible block placement (including start and end positioning).
• archived replaced by in_trash: 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.
• transcription renamed to meeting_notes: The transcription block type has been renamed to meeting_notes across all block endpoints.

Most integrations only need simple find-and-replace updates. See the upgrade guide for step-by-step instructions.

SDK support: @notionhq/client v5.12.0 adds support for 2026-03-11. Upgrade the SDK and set notionVersion: "2026-03-11" to opt in.

Notion MCP: new view tools

Two new tools are available in Notion MCP:

• notion-create-view — Create new database views with filters, sorts, grouping, display properties, and layout-specific settings (calendar, timeline, etc.).
• notion-update-view — Update an existing view’s configuration. Accepts view:// URIs, Notion URLs with ?v=, or bare UUIDs.

See Supported tools for details and example prompts.

Markdown content API improvements

The Update page markdown endpoint now supports two additional command types:

• update_content — Make targeted edits with an array of search-and-replace operations (old_str / new_str). Recommended for precise, multi-site edits.
• replace_content — Replace the entire page content with new markdown in a single operation.

We recommend update_content and replace_content over the older insert_content and replace_content_range commands. See Working with markdown content for usage examples.

Template timezone parameter

The Create page and Update page endpoints now accept an optional timezone field inside the template parameter. This controls how template variables like @now and @today resolve — for example, "America/New_York" ensures dates reflect Eastern Time instead of defaulting to UTC. See the Creating pages from templates guide for details.

Markdown Content API

Three new endpoints let you create, read, and update page content using enhanced markdown instead of the block-based API:

• POST /v1/pages now accepts a markdown parameter as an alternative to children.
• GET /v1/pages/:page_id/markdown retrieves a page’s full content as enhanced markdown.
• PATCH /v1/pages/:page_id/markdown inserts or replaces content using enhanced markdown with ellipsis-based selections.

See Working with markdown content and the Enhanced markdown format reference for details.

AI meeting notes

• The GET /v1/pages/:page_id/markdown endpoint supports an include_transcript query parameter to include full meeting note transcripts in the response.
• Added support for the transcription block type, enabling integrations to read AI meeting notes metadata — including title, status, calendar event details, and pointers to summary, notes, and transcript content blocks.

SDK improvements

• Automatic retry with exponential backoff — the SDK now retries failed requests automatically with configurable backoff (v5.10.0).
• Markdown endpoint methods — pages.retrieveMarkdown() and pages.updateMarkdown() (v5.11.0).

Notion MCP improvements

Highlighting recent changes to Notion MCP:

• Create and fetch comments on blocks, not just pages.
• View Notion Sites pages via the fetch tool.
• Fetch AI meeting transcripts and query meeting notes efficiently with the new notion-query-meeting-notes tool.
• Fetch an individual data source by ID or URL within a database.
• ~91% context token reduction in notion-create-database and notion-update-data-source tools by switching to SQL DDL-based schemas.
• Added update_verification command to the notion-update-page tool.
• Flattened notion-update-page tool parameters and fixed schema issues for improved compatibility with MCP clients.
• Enterprise governance: audit logging for MCP tool usage and admin tool allowlisting.

We recommend reconnecting Notion MCP in your third-party AI tools to ensure you have the most up-to-date tools and resources, and as always, familiarizing yourself and your team with security best practices.

v5.7.0 release notes

We released v5.7.0 of our SDK for JavaScript and TypeScript. Since the last changelog entry, we've added the following fixes and improvements to the Notion API:

• Introduce Move page API to change the parent of an existing page.
• TS/JS example projects extracted to a new open-source project: notion-cookbook.
• Add support for customizing the position of a new page within the parent page.
• New APIs to power the flow described in our Creating pages from templates guide:
  • Introduce List data source templates endpoint.
  • Introduce template parameter to Create Page API.
  • Introduce template and erase_content parameters to Update Page API.

Highlighting recent LLM-facing changes to Notion MCP, our remote Model Context Protocol (MCP) server for AI tools:

• Released notion-query-data-sources tool to Enterprise Notion workspaces with access to Notion AI.
• Tool consolidation: notion-get-user has been removed & its functionality has been rolled into notion-get-users.
• Fixed a bug causing child content to be deleted by the notion-update-page tool when using replace_content and replace_content_range modes.
• Removed Notion-flavored Markdown specification from notion-create-pages tool to conserve context tokens, since it exists behind a dedicated MCP Resource as well.

We recommend reconnecting Notion MCP in your third-party AI tools to ensure you have the most up-to-date tools and resources, and as always, familiarizing yourself and your team with security best practices.

We released v5.1.0 of @notionhq/client, our SDK for JavaScript and TypeScript. This includes the following fixes and improvements:

• Add support for is_locked boolean parameter on update page and database APIs (to update whether a page is locked in the Notion app UI)
• dataSource.update: add support for changing a data source’s parent database
• Remove page_id as a possible parent for CreateDataSourceBodyParameters
• Add request_id to Client log lines

As noted in the library’s README, v5 and above of the SDK isn’t compatible with API versions older than 2025-09-03. See the upgrade guide to learn more.

Important API update coming September 3rd

We're introducing multi-source databases to Notion! Our new API version 2025-09-03 separates “databases” (containers) from “data sources” (tables), unlocking powerful new organizational capabilities.

What you need to know:

• Current integrations continue working with single-source databases
• Update to the new API version to support multi-source databases
• We're introducing the concept of API versioning to integration webhooks as well

Start upgrading your integrations now to ensure a smooth transition when users begin creating additional data sources starting from September 3rd.
Full details and migration guide: Upgrading to 2025-09-03
General information about API versioning: Versioning