Notion Developers Updates & Release Notes

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 and the Enhanced markdown format reference for details.

Developer portal and personal access tokens

The new Developer portal is now available as a single place to manage developer tools for Notion, including connections, Workers, and personal access tokens. Personal access tokens (PATs) are user-scoped tokens for scripts, CLI workflows, Workers, and trusted tools that should act with one Notion user’s permissions. PATs can be granted Notion API access, Workers access, or both. Workspace admins can now view and revoke PATs created in their workspace. On supported plans, admins can also configure who may create PATs with Notion API access. Defaults vary by plan: Free workspaces default to workspace owners only, Plus workspaces default to all workspace members, Business workspaces default to workspace owners only, and Enterprise workspaces default to workspace owners and selected groups.

The new Query meeting notes endpoint (POST /v1/blocks/meeting_notes/query) returns AI meeting notes for the integration’s user with optional filter, sort, and limit. The attendees alias is normalized server-side so filters round-trip cleanly.

Pages and blocks parented by an agent now serialize their parent as { "type": "agent_id", "agent_id": "..." } instead of being rejected or rewritten. See Parent object for the full list of parent types.

SDK support: @notionhq/client v5.21.0 adds typed support for notion.blocks.meetingNotes.query() and the agent_id parent variant.

Improvements to pagination reliability for the Query a data source endpoint

• Pagination cursors now embed a session identifier, eliminating intermittent 400 validation_error (“The start_cursor provided is invalid”) errors that could occur when multiple pagination sessions for the same query overlapped.
• The start_cursor parameter now accepts opaque string values in addition to UUIDs. Existing UUID-based cursors continue to work. As documented in our versioning policy, cursors should always be treated as opaque — pass next_cursor values back as start_cursor without parsing or validating their format.

Data source and view query pagination limit

The Query a data source, Create a view query, and Get view query results endpoints now enforce a maximum pagination depth of 10,000 results per query. When a query matches more rows than this limit, the response includes a new request_status field:

{
  "request_status": {
    "type": "incomplete",
    "incomplete_reason": "query_result_limit_reached"
  }
}

Integrations that polled these endpoints to iterate through all matching rows in a large data source should check for request_status.type === "incomplete" and adapt accordingly. The limit improves reliability for all API users by bounding the server-side resources consumed by each query.

If your integration needs to process all pages in a large data source, we recommend:

• Using data source filters or narrowing the view’s filter/sort configuration to reduce the result set (for example, filter by last_edited_time to only fetch recently changed pages).
• Setting up integration webhooks for incremental sync instead of polling the full data source on a schedule.
• Dividing large data sources into multiple smaller ones.

SDK support: @notionhq/client v5.20.0 adds typed support for the request_status field on affected list responses.

Update and delete comment endpoints

The Update a comment ( PATCH /v1/comments/:comment_id ) and Delete a comment ( DELETE /v1/comments/:comment_id ) endpoints are now generally available. Non-DLP integrations can only modify or delete comments they created.

Multi-value filters for select, status, and multi_select properties

Database and data source filters now accept an array of values for equals / does_not_equal on select and status properties, and for contains / does_not_contain on multi_select properties, matching the multi-value conditions available in the Notion UI. The same schema is used by view filters and quick filters. Person filters set via the API also now round-trip cleanly on read without extra combinator nesting.

Notion MCP improvements

The search tool no longer drops Slack DMs and private channel results when the connected workspace has the Slack integration enabled.

The fetch tool now accepts any first-party Notion domain for the current environment (both notion.so and notion.com), fixing cases where pasted links fell through as generic webpages.

Page resources returned by the fetch tool now include is_archived so agents can tell when a page is in the trash.

The enhanced Markdown guidance the MCP presents to LLMs now documents
as the correct way to break lines inside inline code, preventing retry loops when agents write multi-line inline code via update_page.

The Notion MCP OAuth server adds Client ID Metadata Document (CIMD) support per MCP spec 2025-11-25, letting clients use an HTTPS URL as their client_id instead of going through Dynamic Client Registration.

Comment markdown formatting clarification

The Create a comment and Update a comment references now explicitly document that the markdown body parameter supports inline formatting only — fenced code blocks, headings, lists, tables, and blockquotes do not render as structured blocks in comments.

SDK support : @notionhq/client v5.18.0 adds typed support for multi-value select, status, and multi_select filters. v5.19.0 adds notion.comments.update() and notion.comments.delete().

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.