Notion Developers Updates & Release Notes

Per-tool access map in notion-fetch self

The notion-fetch MCP tool’s self response now includes a current_tool_access map, so clients can tell before making a call which tools will actually run on the connected workspace’s plan and which would only return an upgrade prompt. Each entry’s status is available, limited_free_trial (calls succeed via a free or metered trial allowance), upgrade_required (the entry also carries an upgrade_url into the workspace’s upgrade flow), or not_enabled. See Integrating your own MCP client.

New identity fields in OAuth token responses

User objects now include an email_verified boolean next to person.email, indicating whether Notion has verified that email address. The field appears anywhere person emails do, including the owner in OAuth token responses and List all users results.

Notion MCP token responses now include top-level user_id, workspace_id, and email_domain fields on successful authorization-code exchanges, so MCP clients can associate a connection with a Notion user and workspace without an extra call. See Integrating your own MCP client.

New response fields like these are backwards-compatible additions and appear on every API version. Parse responses leniently: ignore fields you don’t recognize rather than rejecting them.

Notion app links in API responses use the new app domain

As part of Notion’s move from notion.so to notion.com, the links Notion generates for its own records changed in early June 2026: the url values returned for pages, databases, and data sources, and the href values for page and database mentions, now point at the Notion app domain with a page path prefix, https://app.notion.com/p/{page-id}, instead of https://www.notion.so/{page-id}. Existing notion.so links continue to open correctly.

These values are links for people to open in Notion, not stable identifiers: their domain and path format may change again. To reference a record, use its id field rather than parsing the URL, and use a page’s public_url to link to its published site. Links authored by users, such as link.url in rich text and URL property values, and links to sites published on notion.site or custom domains are unchanged.

Search the trash and query archived pages

Search accepts a new filter.in_trash option to list trashed pages and data sources (databases on API versions before 2025-09-03).

Query a data source accepts a top-level is_archived body parameter to return archived pages instead of the default non-archived set.

SDK support: @notionhq/client v5.23.2 adds filter.in_trash support to client.search(). v5.23.1 exports rich text annotation types and fixes pagination helper type compatibility with endpoint methods under strictNullChecks.

Verify webhook signatures with one call

The new verifyWebhookSignature() helper confirms that a webhook event really came from Notion, so you no longer need to hand-write the HMAC check. Pass the raw request body, the X-Notion-Signature header, and your subscription’s verification_token; the helper compares signatures in constant time and returns false instead of throwing on malformed input. It works without configuration in Node.js 18+, Bun, Deno, Cloudflare Workers, Vercel Edge Functions, and browsers. A companion signWebhookPayload() generates signatures for testing your handler.

Read every row in a large data source

A single data source query returns at most 10,000 results, so plain pagination can silently miss rows. The new iterateAllDataSourceRows() and collectAllDataSourceRows() helpers page past the limit using the windowing approach from the Query large data sources guide, de-duplicating rows along the way. Stream rows with the iterator, or collect them into an array when the full result fits in memory.

Start and poll async page writes

notion.asyncTasks.retrieve({ task_id }) adds typed support for the Retrieve an async task endpoint, and the page create and markdown update methods now accept allow_async: true. Together they let you run large markdown writes asynchronously: start the write without holding a request open, then poll until the task succeeds or fails.

Reliability and fixes

• The client now automatically retries service_overload (HTTP 529) responses, respecting the Retry-After header as described in Request limits. Thanks to @RyanBillard for contributing this.
• The relevance sort in search parameters now has the correct type, { property: "relevance" }.
• Pagination parameters accept start_cursor: null, so you can pass a response’s next_cursor straight through without a null check.

Choose an expiration when creating a personal access token

When creating a personal access token in the Developer portal, you can now pick an Expiration of 7 days, 30 days, 90 days, 180 days, or 1 year. The default stays at 1 year, matching the previous behavior. The create dialog previews the exact expiration date, and the reveal step shows the same date next to the token value.

The workspace admin view under Settings & members → Connections now also surfaces an Expired status and filter for PATs whose expiration has passed. Expired tokens stop authenticating and return an unauthorized error, and can still be revoked from the admin view or the Developer portal.

Async page markdown writes

You can now opt into async responses for large page markdown create and update requests. Set allow_async: true when creating a page with POST /v1/pages and the markdown body parameter, or when updating page content with PATCH /v1/pages/:page_id/markdown. Notion returns an async_task handle with status_url and poll_after_seconds, which you can poll until the task succeeds or fails.

Notion MCP also supports async page create and update flows through allow_async: true on notion-create-pages and notion-update-page, plus the notion-get-async-task polling tool. See Working with markdown content for examples.

Your AI assistant now has a complete, consistent view of Notion

We’ve expanded which Notion features are available when using AI assistants like Claude, ChatGPT, or any third-party agent connected to Notion via MCP.

Expanded access for Business + Notion AI plans

Teams on a Business plan with Notion AI can now query a single database or view directly from their AI assistant. This previously required Enterprise + Notion AI. Querying across multiple databases in a single query still requires Enterprise + Notion AI.

Your assistant always knows what’s possible

Previously, if a Notion feature wasn’t included in your plan, your AI assistant simply didn’t know it existed. This sometimes led to bad outcomes. For example, your assistant might repeatedly try to search for database properties, unaware that the right tool simply wasn’t visible to it.

Now your assistant has a complete picture of what Notion can do. If a feature requires a higher plan, it will say so and point you toward an upgrade rather than silently attempting the wrong approach.

Status option groups

Status property option objects now accept an optional group field when creating or updating a database or data source schema. Use group to assign a custom status option to To-do, In progress, or Complete. When group is omitted on update, existing options keep their current group, and new options use To-do when present or the first existing group otherwise.

Bots that appear as user objects in API responses can now be assigned to people page property values and referenced in user rich text mentions. You can set a people property when you create a page or update page properties. Previously these writes returned a validation_error, even though the same bots were already returned when reading those fields. Some bots never appear as user objects, including integrations Notion uses internally to power features like database automations and custom agents. Assigning one of those still returns a validation_error.

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.