apiwatch

All changes / Notion

Deprecation rest

Notion Agent APIs are generally available and the private alpha routes (agents list, threads, messages, chat, chatStream) are deprecated in favor of sessions and events

Took effect · Notion Agent APIs private alpha routes (GET /v1/agents, GET /v1/agents/:agent_id/threads, POST /v1/agents/:agent_id/threads/query, GET /v1/threads/:thread_id/messages, POST /v1/threads/:thread_id/messages/query, POST /v1/agents/:agent_id/chat, POST /v1/agents/:agent_id/chatStream)

Reviewed against the vendor source on Nov 4, 2026 (AI-assisted review). Key facts are re-checked against the source daily.

What changes

On November 2, 2026, Notion made the Notion Agent APIs generally available and deprecated the private alpha routes. Each has a replacement: GET /v1/agents becomes POST /v1/agents/query (query parameters move into a filter object); GET /v1/agents/:agent_id/threads and POST /v1/agents/:agent_id/threads/query become POST /v1/sessions/query filtered on agent_id; GET /v1/threads/:thread_id/messages and POST /v1/threads/:thread_id/messages/query become POST /v1/sessions/:session_id/events/query; POST /v1/agents/:agent_id/chat becomes POST /v1/sessions with agent_id in the body; POST /v1/agents/:agent_id/chatStream becomes POST /v1/sessions with Accept text/event-stream, sending server-sent events instead of NDJSON lines. Threads and messages become sessions and events, thread_id becomes session_id, and sessions add the statuses queued, in_progress and terminated (queued and in_progress replace the alpha's pending). No removal date has been announced.

Deprecation: Still works; removal is announced.

What to do

Move each alpha call to its replacement in Notion's Upgrading from the alpha routes guide. Use POST /v1/agents/query for listing agents, POST /v1/sessions/query (filter on agent_id) for threads, POST /v1/sessions/:session_id/events/query for messages (agent replies are agent.message events with content parts), and POST /v1/sessions with agent_id in the body for chat. For chatStream, send POST /v1/sessions with Accept text/event-stream and parse server-sent events instead of NDJSON. Rename thread_id to session_id, and handle the queued, in_progress and terminated statuses (treat unknown statuses as non-terminal). In @notionhq/client use notion.agents.query and the notion.sessions methods.

Strings to search for

/chatStream/threads/query/messages/query/chat/threads/messages/v1/agentsthread_messagechat.invocation

Not affected (matches inside these are ignored): /v1/agents/, /chat/completions, /api/chat, /v1/messages, api.openai.com/v1/threads, api.mistral.ai/v1/agents, ("/chat", ('/chat', ("/threads", ('/threads', ("/messages", ('/messages'

Counts only in files that mention notion + chatStream or notion + agents/ or notion + threads/ or notion + /v1/agents or notion + thread_message or notion + chat.invocation.

Source

https://developers.notion.com/page/changelog