Chat with agents
Use sessions to start a chat, stream the agent’s reply, submit an action when needed, and read its event history. These endpoints let you bring Custom Agents or the personal agent into a Slack bot, internal tool, or mobile client.Create or update a session
Start a session, send a message, submit an action, or stream a turn.
Retrieve a session
Read the current state of a session.
Query sessions
Find accessible sessions.
Query session events
Page through a session’s event history.
Cancel a session
Stop an in-progress session.
Manage agents
Find the agents your token can access, track their usage, and change their settings, status, and credit limits. Use these endpoints to build a usage dashboard or an administrative console for Custom Agents.Query agents
Find the agents the integration can access.
Retrieve an agent
Get one agent’s metadata.
Retrieve agent insights
Read credits used and runs completed for a Custom Agent or your personal agent.
Update an agent
Change an agent’s name, model, status, or favorite state.
Update an agent credit limit
Set or clear a Custom Agent’s credit limit.
Batch manage agent
Apply several agent management operations asynchronously.
Delete an agent
Soft-delete a Custom Agent you no longer need.
Authentication and access
You can authenticate API requests with either a personal access token or a connection token:- A personal access token acts as you and uses your existing access to Custom Agents.
- A connection token can access Custom Agents shared with its connection. To read agents and start or read sessions, it needs the View sessions and interact with agents capability. To update an agent or change its status, it needs the Edit selected agents capability. A connection can’t delete an agent or change a credit limit. A connection with only Edit selected agents gets a
403from the read and session endpoints. See Connection capabilities for details.
notion_ai. Only a personal access token can use it, and it always means the personal agent of the user the token acts as. A connection token receives a 404 object_not_found for notion_ai. You can chat with the personal agent, read its insights, and change its name and model. It has no status control or credit limit, and you can’t delete it. Sessions you start with it belong to you, like any session you start with a personal access token.
Access requirements
Access to a Custom Agent is evaluated per agent, using the same permissions that apply in Notion:
- Read access lets you read a Custom Agent. Session access has its own rules, described below.
- Edit access lets you update a Custom Agent’s name, description, model, or status. With a personal access token, it also lets you delete the agent. Workspace admins can also delete agents with the Admin API.
- Full access lets you read a Custom Agent’s credit limit. Otherwise, the limit is
hidden. Only a personal access token for a user with full access can change it through this API. Workspace admins can also change it with the Admin API.
- A connection token can read only the sessions its connection created. This holds even when the connection can view or edit the Custom Agent. It can’t read chats in the Notion app, trigger runs, or sessions from other connections.
- A personal access token can read the sessions you created, in Notion or with any of your personal access tokens in that workspace. Replacing or revoking a token doesn’t hide its sessions from your other tokens. It can read other sessions on a Custom Agent if you can comment on or edit that Custom Agent in Notion.
- Wider read access does not extend to writes. A connection token can send messages to, update, or cancel only the sessions its connection created. A personal access token can do so only for sessions you created.
- Retrieving a session you can’t read, or its events, returns
404object_not_found. Query sessions leaves it out of the results instead.