Notion Developers Updates & Release Notes

Page covers and icons in notion-fetch responses

The notion-fetch MCP tool now returns cover and icon metadata for pages and database items. Both use the same shapes as the REST API, so clients can inspect the current cover or icon before deciding whether to replace it.

Rich text in data source queries

The notion-query-data-sources MCP tool now supports mode: "rows" to keep rich text in data source results. This mode preserves mentions and link targets that SQL output can omit.

Typed databases in the REST API

Create a database now accepts an optional database_type of tasks, projects, or skills. Notion builds the database from its canonical schema and metadata for that type, so the result matches a database of that type created in the Notion app. database_type can’t be combined with initial_data_source, and when title is omitted the database is named after its type. See Typed databases for the properties each type creates. Database and data source objects now include a read-only database_type field.

Free workspace block limits now apply to the REST API

Starting today, the REST API enforces the existing Free workspace block limit for internal connections and OAuth connections restricted to selected workspaces. This is not a new workspace limit. See Workspace block limits for the grace period, HTTP 403 response, and background template behavior.

Upgrade prompts for Custom Agent tools in Notion MCP

Notion MCP’s — notion-list-agents, notion-search-agents, and the session tools — now return a prompt with a recovery link when the workspace doesn’t have access to Notion AI and Custom Agents. They previously returned a generic permission error with no recovery link. notion-fetch with the id self also reports these tools as upgrade_required with an upgrade_url, or as plan_required with a landing_page_url and landing_page_action when Notion routes the user through a plan landing page. Clients can use this status to route around unavailable tools before calling.

Workspaces with a billing restriction, such as an unpaid invoice, are treated separately: the tools return a permission error that asks a workspace owner to manage billing, and current_tool_access reports them as not_enabled rather than upgrade_required.

A connection that lacks the “View threads and interact with agents” capability does not advertise these tools and must reconnect or re-authorize.

Capture ideas and draft content in Notion

Your agent can now capture ideas and draft content in Notion without choosing where the page belongs first. The page starts as a private draft, so you can review it and organize it later.

Save and reuse your preferred workflows with Notion Skills

When you ask your AI to save a workflow you want to reuse, it can now create a Notion Skill or turn an existing page into one. Skills are reusable instructions stored as Notion pages that you own and can edit. When you ask for that workflow later, your AI can find the right Skill and read its instructions before starting.

Find the right page more easily

Your AI can now narrow Notion searches by where a page lives, who created or edited it, when it changed, whether the title matches, and the page’s status. It can also sort results and look through up to 50 matches. Search results now show more context, including where a page lives and whether Notion has verified it. This helps your AI choose between similar or conflicting pages before reading the full content. Every plan includes filters for creator, creation date, and a single page, data source, or teamspace. On Business and Enterprise plans, your AI can also filter by editor, last-edited date, multiple teamspaces, title, or content status, and sort by date.

Fetch saved database views in Notion MCP

Notion MCP’s notion-fetch now accepts view:// URLs to read saved view settings. Tool response text now names fetch instead of view, without changing page content.

Custom Agent session tools in Notion MCP

Notion MCP now supports finding and working with Custom Agent sessions. The new tools can query or search sessions, start a session, send a follow-up message, check or wait for its status, stop a run, and list or read session events. See Supported tools for the full tool list and examples.

Atomic batched content updates in Notion MCP

notion-update-page calls that use the update_content command now apply every content-changing replacement in the batch or none of them. Previously, when one old_str matched no page content and another one in the same call did, the matching replacements were saved and the call returned success — so a batch that removed content in one operation and reinserted it in another could drop that content. These calls now return a validation_error naming the old_str that wasn’t found, and the page is left unchanged. Operations whose old_str and new_str are identical are ignored without checking for a match. See Supported tools for the tool’s matching rules.

old_str must also be a non-empty string. Empty values were previously ignored, which silently skipped the replacement; they now fail validation on both notion-update-page and Update a page’s content as markdown.

Notion Agent APIs in public beta

The Notion Agent APIs are now in public beta. Use sessions to start a chat with a Custom Agent, stream its reply, submit an action, and page through a session’s event history, so you can bring Custom Agents into a Slack bot, an internal tool, or a mobile client. The quickstart walks through a first request end to end with a personal access token.

The beta also covers managing Custom Agents programmatically: find the agents a token can reach with Query agents, read per-agent usage with Retrieve agent insights, and set credit limits, enable, disable, or delete agents — individually or in an asynchronous batch.

If you built against the private alpha routes for agents, threads, messages, or chat, see Upgrading to public beta. The replacements take JSON request bodies instead of query parameters and return sessions and events instead of threads and messages. Migrate off the alpha routes by September 30, 2026.

More filters in Notion MCP view tools

The notion-create-view and notion-update-view tools now apply relation, person, status, created by, last edited by, unique ID, last visited, verification, and place filters. Previously, some calls succeeded but saved a view without the requested filter.

Use a page URL or ID for relation filters and a user ID or "me" for person filters. Invalid values now return an error. See Supported tools for accepted values, and read the notion://docs/view-dsl-spec resource for the full configuration syntax.

Verification filters now round-trip through view responses for both matching (status) and non-matching (does_not_equal) conditions. Data source queries accept the same conditions.

Updating the query tool list in Notion MCP

New tool-list responses no longer include notion-query-database-view. Use notion-query-data-sources with mode: "view" for saved views. Clients with a cached tool list can still call notion-query-database-view; those calls continue to work and return migration guidance.

The current_tool_access map returned by notion-fetch with the id self no longer has a query_database_view entry, since the map describes the tools that a current tool list advertises. See Supported tools for the tool list.

Multi-source SQL on Business plans in Notion MCP

Multi-source SQL queries that span multiple data sources now work on Business plans with Notion AI, which previously required an Enterprise plan. SQL is unlimited on Business and Enterprise plans with Notion AI; other plans keep the metered single-data-source allowance, and saved-view mode stays free on every plan.

JS SDK updates

@notionhq/client v5.25.1 fixes the isFullDataSource and isFullDatabase type guards, which previously accepted partial responses and narrowed them to the full type. Both now require the title field, the same structural check the other full-object guards use. isFullPageOrDataSource picks up the fix.

v5.25.2 adds the does_not_equal condition to verification property filters in data source and database query request types, alongside the existing status condition.

prop() references in formula property writes

Formula expressions submitted through Update a data source now store prop("Property Name") references exactly as written. Previously, the API accepted some expressions but silently rewrote them — most visibly, a reference to a unique ID property dropped the ID’s prefix from computed values, and a prop() reference inside an array literal emptied the array. Expressions the API can’t store now return a validation_error instead. Formulas saved before this fix keep their old stored expression until you resubmit the update.

Formula properties created through the API also now keep their result type, so number formatting options stay available in Notion and other formulas can reference them with prop().

Readable formula expressions in data source schemas

Retrieve a data source is beginning to return formula expressions using the same prop("Property Name") syntax you write. This change is rolling out gradually over the coming days; expressions that can’t be rendered faithfully in this syntax continue to use the internal property reference syntax.

Admin API reference for agents

The Admin API reference now covers the endpoints for managing agents in a workspace: credit usage and limits, permissions, status, creation policy, and workflow metadata.

Filter properties on page writes

Create a page and Update page properties now accept the same filter_properties query parameter as Retrieve a page. Pass the IDs of the properties you want, and the write response includes only those properties. This keeps responses small and fast for pages with many properties.

SDK support: @notionhq/client v5.25.0 adds filter_properties to pages.create() and pages.update().

Truncation metadata on notion-fetch

The notion-fetch MCP tool response now includes truncated, unknown_block_ids, and unknown_block_count when a page is large enough that some subtrees could not be loaded. unknown_block_ids lists up to 50 omitted subtree root IDs, and unknown_block_count reports the total number of omitted subtree roots. Pass a returned ID back to notion-fetch to retrieve that subtree directly; treat an object_not_found error on retry as a signal that the caller does not have access to the subtree.

unsupported formula and rollup property values

The API can now return formula and rollup page property values and property item values with type set to "unsupported" and an empty unsupported object. This happens when a value depends on too many related pages or nested formulas and rollups. The response doesn’t include a partial value. Treat the property as unavailable. Rollups still include the function field. To make the value available, reduce the number of related pages or simplify the nested formulas and rollups.

JavaScript SDK 5.24.0

We released @notionhq/client v5.24.0. It adds client.blocks.meetingNotes.create() for creating a meeting note, typed unsupported formula and rollup values, and APIErrorCode.InvalidBeta for handling invalid_beta responses.

Clearer per-tool access status

The current_tool_access status previously called limited_free_trial is now available_with_limit. The new name makes clear that a tool is available until the usage limit included with the workspace’s plan is reached. This is a naming and description update only; it does not change tool availability or usage limits.

Fetch documentation resources with the fetch tool

The Notion MCP fetch tool now accepts notion://docs/* URIs (for example, notion://docs/enhanced-markdown-spec) and returns the same content as the MCP resource of the same URI. This gives MCP clients that cannot read MCP resources a way to load the specs referenced in tool descriptions.