Skip to main content
POST
Chat with agent
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.
By default, this endpoint returns a JSON chat.invocation response. To stream the agent response as newline-delimited JSON (NDJSON), send Accept: application/x-ndjson. Each line in a streaming response is a complete JSON chunk. The stream supports the optional verbose query parameter; set verbose=false to omit verbose agent output such as thinking and tool activity.

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
deprecated

Deprecated. Use POST /v1/threads/:thread_id/messages to continue an existing thread. If not provided, a new thread will be created.

Response

object
string
required

Always chat.invocation

Allowed value: "chat.invocation"
agent_id
string
required
thread_id
string
required
invocation_id
string
required
status
string
required

Always pending

Allowed value: "pending"