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
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