Chat with Agent (Streaming)
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:
messagechunks are upserts keyed byid(the same message may be emitted multiple times as tool results arrive).- When
verbose=false, agentmessagechunks omitcontent_partsand only includecontent. errorchunks are emitted when the agent encounters a failure during inference. Thecodefield contains a programmatic error code (e.g.internal_server_error,rate_limited,restricted_resource) and themessagefield contains a human-readable description.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
The API version to use for this request. The latest version is 2026-03-11.
2026-03-11 Path Parameters
The ID of the agent to chat with. Use a UUID for custom agents or notion_ai for Notion Agent (personal agent); the reserved UUID 33333333-3333-3333-3333-333333333333 remains supported for backward compatibility.
Query Parameters
Whether to include agent thinking and structured message content parts. Defaults to false.
Body
The message to send to the agent.
10000An array of file uploads to attach to this chat turn. Use the File Upload APIs to create uploads and pass their IDs here.
100Optional caller-provided string metadata persisted with the user message. user_id is used for lifecycle correlation and does not change authorization.
Additional caller-provided context for the agent to consider while responding.
10000The ID of an existing thread to continue the conversation. If not provided, a new thread will be created.
Response
- Message
- Tool
- Started
- Done
- Waiting for user
- Error
A single NDJSON chunk from the chat streaming response. Each line in the stream is one of these chunk types.
Always message
"message"One of: user, agent
user, agent Text appended since the previous chunk for this message. Empty for metadata-only updates. If previously emitted text is revised, this contains the full current text. The cumulative content field remains authoritative.
100100- Option 1
- Option 2
- Option 3
- Option 4
- Option 5