Notion Agent APIs are generally available, including the personal agent
TL;DR
On November 2, 2026, Notion marked the Notion Agent APIs generally available and deprecated the private alpha routes. A personal access token can chat with and manage the personal agent (Notion AI) by passing notion_ai as the agent_id. The new Update an agent endpoint, PATCH /v1/agents/{agent_id}, changes name, description, model, status, or favorite state and replaces the deprecated Update agent status endpoint.
- Status
- Live
- Released
- Plans
- Not specified
What changed
On November 2, 2026, Notion marked the Notion Agent APIs generally available. They are out of beta. Private alpha routes are deprecated. Notion points people still on those routes to Upgrading from the alpha routes.
The same section adds the personal agent, which Notion also calls Notion AI:
- Use a personal access token. The id
notion_aiis that token user's personal agent, not a shared workspace agent. - With that id you can start a session, retrieve the agent, read its insights, and change its name and model.
- A connection token that requests
notion_aigets a404object_not_found. - The personal agent has no status control and no credit limit, and you cannot delete it.
Update an agent is new: PATCH /v1/agents/{agent_id}. One request can change name, description, model, status, or favorite state. The favorite field in the API reference is is_favorited. Send only the fields you want to change. Update agent status is deprecated. Send status (active or disabled) to Update an agent instead. notion_ai accepts name and model on that endpoint. Other fields return a 400 validation_error.
These APIs entered public beta on August 20, 2026, with sessions for Custom Agents and endpoints to query agents, read insights, and manage status, credit limits, and deletion. That note asked private-alpha customers to migrate by September 30, 2026. The Notion 3.7 release notes separately described an Agent SDK in public beta on Business and Enterprise. Notion MCP session tools are a different surface. They run through an MCP connection, not these REST routes.
The November 2 changelog and the Agent APIs overview do not state a plan requirement for general availability.
Why it matters
A Slack bot, internal tool, or mobile client that chats with a Custom Agent can stay on the current session routes and drop the alpha thread and message routes. The upgrade guide maps each alpha route to its replacement.
Someone building with their own Notion AI can now do that through a personal access token and notion_ai, instead of only through Custom Agents shared with a connection. The token acts as that person, and sessions started this way belong to them, including in the Notion app.
Admin tooling can change name, description, model, status, and favorite state in one request. Keep using the separate credit-limit endpoint for a Custom Agent's limit. Sending credit_limit to Update an agent returns a 400 validation_error.
Frequently asked questions
Are the Notion Agent APIs still in beta?
No. Notion marked them generally available on November 2, 2026. Private alpha routes are deprecated.
How do I chat with Notion AI through the Agent APIs?
Use a personal access token and set agent_id to notion_ai. You can start a session, retrieve the agent, read its insights, and change its name and model. A connection token cannot use that id.
What replaced Update agent status in the Notion API?
Update an agent. Send status on PATCH /v1/agents/{agent_id} instead of the deprecated Update agent status endpoint. The personal agent has no status control.
Which Notion plans include the Agent APIs now that they are generally available?
Notion's November 2 changelog and the Agent APIs overview do not say. The September 15, 2026 release notes described the then-beta Agent SDK as Business and Enterprise.