Skip to main content
POST
/
v1
/
agents
/
{agent_id}
/
chat
Chat with agent
curl --request POST \
  --url https://api.notion.com/v1/agents/{agent_id}/chat \
  --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>"
    }
  ]
}
'
{
  "object": "<string>",
  "agent_id": "<string>",
  "thread_id": "<string>",
  "status": "<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 integrations.

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 2025-09-03.

Available options:
2025-09-03

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).

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

object
string
required

Always chat.invocation

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

Always pending

Allowed value: "pending"