Skip to main content
Build apps and integrations that bring Custom Agents into the tools and workflows your team already uses. With the Notion Agent APIs, you can power chat experiences outside Notion and manage Custom Agents programmatically.
This API is in public beta

​
Chat with Custom 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 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 Custom Agents

Find the Custom Agents your token can access, track their usage, and manage their status and credit limits. Use these endpoints to build a usage dashboard or an administrative console for Custom Agents.

Query agents

Find Custom Agents the integration can access.

Retrieve an agent

Get one Custom Agent’s metadata.

Retrieve agent insights

Read credits used and runs completed for a Custom Agent or your personal agent.

Update agent status

Enable or disable a Custom Agent.

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 needs the Interact with agents capability and can access Custom Agents shared with its connection.
Access requirements Access is evaluated per Custom Agent, using the same permissions that apply in Notion:
  • Read access lets you read a Custom Agent and its sessions.
  • Edit access lets you change a Custom Agent’s status or delete it.
  • Full access lets you read or change a Custom Agent’s credit limit. Otherwise, the limit is hidden.