Skip to main content
POST
Chat with agent (streaming)
This endpoint is deprecated. Use POST /v1/agents/{agent_id}/chat with Accept: application/x-ndjson instead. The legacy endpoint remains available for compatibility.
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 notion_ai for Notion Agent (personal agent); the reserved UUID 33333333-3333-3333-3333-333333333333 remains supported for backward compatibility.

Query Parameters

verbose
boolean

Whether to include agent thinking and structured message content parts. Defaults to false.

Body

application/json
message
string

The message to send to the agent.

Maximum string length: 10000
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
metadata
object

Optional caller-provided string metadata persisted with the user message. user_id is used for lifecycle correlation and does not change authorization.

prompt_context
string

Additional caller-provided context for the agent to consider while responding.

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.

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"
invocation_id
string
required
id
string<uuid>
required
role
enum<string>
required

One of: user, agent

Available options:
user,
agent
content
string
required
delta
string
required

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.

attachments
object[]
Maximum array length: 100
content_parts
object[]
Maximum array length: 100