Quickstart

This API is in public beta

Prerequisites

A Custom Agent to chat with You need an existing Custom Agent because it’s the Agent you’ll chat with in this quickstart. In step 1, you’ll use the API to choose the Agent, then use its ID to start a chat in step 2. The API works with Custom Agents that already exist in the Notion app; it does not create them. To create a new Custom Agent, see Build a Custom Agent. A personal access token to authenticate requests This quickstart sends API requests on your behalf, so each request needs a personal access token (PAT). It lets you authenticate as yourself without setting up OAuth and carries your own access, so it can reach exactly the Custom Agents you can reach in Notion.

Open Personal access tokens in the Developer portal.

Select New token.

Enter a name, select the Notion API capability, and then select Create token. That capability covers the Agents API — there is nothing else to enable.

Copy the token and save it somewhere secure. You won’t be able to see it again.

Set the token as an environment variable so you can use it in the examples below. This lasts for your current terminal session — run it again if you open a new window.

export NOTION_API_KEY=ntn_***

$env:NOTION_API_KEY = "ntn_***"

Step 1: Pick a Custom Agent

Pick the Custom Agent you want to chat with. It can be the Custom Agent you created for this quickstart or an existing Custom Agent in your workspace that you can access. Use Query agents to find it. The example below narrows results to Custom Agents you created. Remove the created_by filter to choose another Custom Agent you can access.

curl

curl -X POST https://api.notion.com/v1/agents/query \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "property": "created_by",
      "people": { "contains": "me" }
    },
    "sorts": [{ "property": "created_time", "direction": "descending" }],
    "page_size": 10
  }'

You get back a list of your Custom Agents, most recently created first:

Response

{
  "object": "list",
  "type": "agent",
  "results": [
    {
      "object": "agent",
      "id": "1f0c7c06-781b-4987-9986-5c8dd3028013",
      "agent_type": "custom_agent",
      "name": "Quickstart agent",
      "description": "Answers questions concisely.",
      "instructions_page_id": "1f0c7c06-781b-4987-9986-5c8dd3028020",
      "icon": { "type": "emoji", "emoji": "🤖" },
      "model": { "mode": "pinned", "id": "claude-sonnet-5" },
      "connections": [],
      "status": "active",
      "pause_reason": null,
      "created_by": {
        "type": "user",
        "id": "9f7dd486-3431-4f8b-b8bf-491287953a01"
      },
      "agent_version": {
        "id": "1f0c7c06-781b-4987-9986-5c8dd3028021",
        "number": 1,
        "published_at": "2026-08-14T12:04:11.000Z"
      },
      "created_time": "2026-08-14T12:00:00.000Z",
      "last_edited_time": "2026-08-14T12:04:11.000Z",
      "last_run_at": null,
      "credit_limit": null,
      "triggers": []
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Copy the id of the Custom Agent you chose — that’s what you’ll chat with. Save it as an environment variable too:

export AGENT_ID=1f0c7c06-781b-4987-9986-5c8dd3028013

$env:AGENT_ID = "1f0c7c06-781b-4987-9986-5c8dd3028013"

Step 2: Start a new Agent chat

Send your agent a message by creating a session with Create or update a session. A session is one conversation: you create it with the first message, then keep sending to the same session_id to continue.

curl

curl -X POST https://api.notion.com/v1/sessions \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent_id\": \"$AGENT_ID\",
    \"message\": \"What can you help me with?\"
  }"

The response is the new session:

Response

{
  "object": "session",
  "id": "2a1c7c06-781b-4987-9986-5c8dd3028014",
  "agent_id": "1f0c7c06-781b-4987-9986-5c8dd3028013",
  "title": "Capabilities question",
  "status": "queued",
  "created_at": "2026-08-14T12:10:00.000Z",
  "updated_at": "2026-08-14T12:10:00.000Z"
}

Save the session ID so the follow-up requests can use it:

export SESSION_ID=2a1c7c06-781b-4987-9986-5c8dd3028014

$env:SESSION_ID = "2a1c7c06-781b-4987-9986-5c8dd3028014"

Step 3: Read the Agent reply

The agent works asynchronously, so the session comes back as queued. Poll Retrieve a session until the status leaves queued and in_progress:

curl

curl https://api.notion.com/v1/sessions/$SESSION_ID \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11"

Stream the response instead. To watch the turn as it happens instead of polling, send the same create request with Accept: text/event-stream. See Create or update a session. Once the status is completed, read the Agent reply from the session’s event history with Query session events:

curl

curl -X POST https://api.notion.com/v1/sessions/$SESSION_ID/events/query \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{ "filter": { "property": "type", "event_type": { "equals": "agent.message" } } }'

The agent’s answer comes back as an agent.message event:

Response

{
  "object": "list",
  "type": "session_event",
  "session_event": {},
  "results": [
    {
      "object": "session_event",
      "id": "3b2c7c06-781b-4987-9986-5c8dd3028015",
      "session_id": "2a1c7c06-781b-4987-9986-5c8dd3028014",
      "sequence": 102,
      "created_at": "2026-08-14T12:10:04.000Z",
      "type": "agent.message",
      "content": [
        { "type": "text", "text": "I can help you draft and summarize documents." }
      ],
      "created_by": {
        "id": "1f0c7c06-781b-4987-9986-5c8dd3028013",
        "type": "bot"
      },
      "metadata": { "model": "claude-sonnet-5" }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

That’s a full round trip: you sent a message to a Custom Agent and read its response from the session events.

Common questions

I don't see Agents in the sidebar

Custom Agents are available on Business and Enterprise plans. Ask a workspace owner whether your workspace is on an eligible plan.

I don't see the option to create a token

On Business and Enterprise plans, PAT creation is restricted by default. Ask a workspace owner to enable it in Settings → Connections.See Who can create PATs.

How do I use the examples in PowerShell?

The curl examples are written for a Unix shell. In PowerShell, refer to the variables as $env:NOTION_API_KEY, $env:AGENT_ID, and $env:SESSION_ID.

How else can I find a Custom Agent?

Query agents also takes a free-text query that matches names and descriptions, along with filters on fields like id, agent_type, created_time, and connections. Sorting is available on created_time and last_run_at.

Next steps

You’ve found a Custom Agent through the API and started a chat. From here you can:

Keep the conversation going. Send another message to the same session_id for a follow-up, or submit an action the agent is waiting on.
Track what your agents cost. Read agent insights for credits used and runs completed per agent to build a usage dashboard.
Set guardrails. Give an agent a credit limit, or disable it when something looks wrong.
Batch manage agent. Apply status, credit-limit, and delete operations in a single asynchronous batch.

See the Overview for the full set of endpoints.

Get started

Agent APIs

API versions

Data APIs

Resources

Compliance

Link previews

Prerequisites

Step 1: Pick a Custom Agent

Step 2: Start a new Agent chat

Step 3: Read the Agent reply

Common questions

Next steps

​Prerequisites

​Step 1: Pick a Custom Agent

​Step 2: Start a new Agent chat

​Step 3: Read the Agent reply

​Common questions

​Next steps

Prerequisites

Step 1: Pick a Custom Agent

Step 2: Start a new Agent chat

Step 3: Read the Agent reply

Common questions

Next steps