Skip to main content
POST
/
v1
/
agents
/
{agent_id}
/
chatStream
Chat with agent (streaming)
curl --request POST \
  --url https://api.notion.com/v1/agents/{agent_id}/chatStream \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Notion-Version: <notion-version>' \
  --data '
{
  "message": "<string>",
  "thread_id": "<string>",
  "attachments": [
    {
      "file_upload": {
        "id": "<string>"
      },
      "type": "<string>",
      "name": "<string>"
    }
  ]
}
'
{
  "type": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "content": "<string>",
  "attachments": [
    {
      "name": "<string>",
      "content_type": "<string>",
      "url": "<string>",
      "expiry_time": "2023-11-07T05:31:56Z"
    }
  ],
  "content_parts": [
    {
      "type": "<string>",
      "text": "<string>"
    }
  ]
}
This is an internal/undocumented endpoint. It is not part of the public API and may change without notice. Do not rely on this endpoint for production connections.
This endpoint returns a newline-delimited JSON (NDJSON) stream. Each line is a complete JSON object (a “chunk”). In the OpenAPI renderer, the application/json schema represents the shape of a single chunk. The actual HTTP response body is application/x-ndjson (a stream of these chunks). Notes:
  • message chunks are upserts keyed by id (the same message may be emitted multiple times as tool results arrive).
  • When verbose=false, agent message chunks omit content_parts and only include content.
  • error chunks are emitted when the agent encounters a failure during inference. The code field contains a programmatic error code (e.g. internal_server_error, rate_limited, restricted_resource) and the message field contains a human-readable description.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Notion-Version
enum<string>
required

The API version to use for this request. The latest version is 2026-03-11.

Available options:
2026-03-11

Path Parameters

​
agent_id
required

The ID of the agent to chat with. Use a UUID for custom agents, or 33333333-3333-3333-3333-333333333333 for the personal agent (Notion AI).

Query Parameters

​
verbose
boolean

Whether to include verbose agent output (thinking, tool calls, tool results). Defaults to true.

Body

application/json
​
message
string

The message to send to the agent.

Maximum string length: 10000
​
thread_id
string

The ID of an existing thread to continue the conversation. If not provided, a new thread will be created.

​
attachments
object[]

An array of file uploads to attach to this chat turn. Use the File Upload APIs to create uploads and pass their IDs here.

Maximum array length: 100

Response

A single NDJSON chunk from the chat streaming response. Each line in the stream is one of these chunk types.

​
type
string
required

Always message

Allowed value: "message"
​
id
string<uuid>
required
​
role
enum<string>
required

One of: user, agent

Available options:
user,
agent
​
content
string
required
​
attachments
object[]
Maximum array length: 100
​
content_parts
object[]
Maximum array length: 100