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>",
"attachments": [
{
"file_upload": {
"id": "<string>"
},
"type": "file_upload",
"name": "<string>"
}
],
"metadata": {},
"prompt_context": "<string>",
"thread_id": "<string>"
}
'import requests
url = "https://api.notion.com/v1/agents/{agent_id}/chat"
payload = {
"message": "<string>",
"attachments": [
{
"file_upload": { "id": "<string>" },
"type": "file_upload",
"name": "<string>"
}
],
"metadata": {},
"prompt_context": "<string>",
"thread_id": "<string>"
}
headers = {
"Notion-Version": "<notion-version>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Notion-Version': '<notion-version>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
message: '<string>',
attachments: [{file_upload: {id: '<string>'}, type: 'file_upload', name: '<string>'}],
metadata: {},
prompt_context: '<string>',
thread_id: '<string>'
})
};
fetch('https://api.notion.com/v1/agents/{agent_id}/chat', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.notion.com/v1/agents/{agent_id}/chat",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'message' => '<string>',
'attachments' => [
[
'file_upload' => [
'id' => '<string>'
],
'type' => 'file_upload',
'name' => '<string>'
]
],
'metadata' => [
],
'prompt_context' => '<string>',
'thread_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Notion-Version: <notion-version>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.notion.com/v1/agents/{agent_id}/chat"
payload := strings.NewReader("{\n \"message\": \"<string>\",\n \"attachments\": [\n {\n \"file_upload\": {\n \"id\": \"<string>\"\n },\n \"type\": \"file_upload\",\n \"name\": \"<string>\"\n }\n ],\n \"metadata\": {},\n \"prompt_context\": \"<string>\",\n \"thread_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Notion-Version", "<notion-version>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.notion.com/v1/agents/{agent_id}/chat")
.header("Notion-Version", "<notion-version>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"message\": \"<string>\",\n \"attachments\": [\n {\n \"file_upload\": {\n \"id\": \"<string>\"\n },\n \"type\": \"file_upload\",\n \"name\": \"<string>\"\n }\n ],\n \"metadata\": {},\n \"prompt_context\": \"<string>\",\n \"thread_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.notion.com/v1/agents/{agent_id}/chat")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"message\": \"<string>\",\n \"attachments\": [\n {\n \"file_upload\": {\n \"id\": \"<string>\"\n },\n \"type\": \"file_upload\",\n \"name\": \"<string>\"\n }\n ],\n \"metadata\": {},\n \"prompt_context\": \"<string>\",\n \"thread_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"object": "chat.invocation",
"agent_id": "<string>",
"thread_id": "<string>",
"invocation_id": "<string>",
"status": "pending"
}{
"object": "error",
"message": "<string>",
"code": "invalid_json",
"status": 400,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "unauthorized",
"status": 401,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "restricted_resource",
"status": 403,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "object_not_found",
"status": 404,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "row_limit_exceeded",
"status": 406,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "conflict_error",
"status": 409,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "rate_limited",
"status": 429,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "internal_server_error",
"status": 500,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "service_unavailable",
"status": 503,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "gateway_timeout",
"status": 504,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "service_overload",
"status": 529,
"additional_data": {}
}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>",
"attachments": [
{
"file_upload": {
"id": "<string>"
},
"type": "file_upload",
"name": "<string>"
}
],
"metadata": {},
"prompt_context": "<string>",
"thread_id": "<string>"
}
'import requests
url = "https://api.notion.com/v1/agents/{agent_id}/chat"
payload = {
"message": "<string>",
"attachments": [
{
"file_upload": { "id": "<string>" },
"type": "file_upload",
"name": "<string>"
}
],
"metadata": {},
"prompt_context": "<string>",
"thread_id": "<string>"
}
headers = {
"Notion-Version": "<notion-version>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Notion-Version': '<notion-version>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
message: '<string>',
attachments: [{file_upload: {id: '<string>'}, type: 'file_upload', name: '<string>'}],
metadata: {},
prompt_context: '<string>',
thread_id: '<string>'
})
};
fetch('https://api.notion.com/v1/agents/{agent_id}/chat', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.notion.com/v1/agents/{agent_id}/chat",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'message' => '<string>',
'attachments' => [
[
'file_upload' => [
'id' => '<string>'
],
'type' => 'file_upload',
'name' => '<string>'
]
],
'metadata' => [
],
'prompt_context' => '<string>',
'thread_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Notion-Version: <notion-version>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.notion.com/v1/agents/{agent_id}/chat"
payload := strings.NewReader("{\n \"message\": \"<string>\",\n \"attachments\": [\n {\n \"file_upload\": {\n \"id\": \"<string>\"\n },\n \"type\": \"file_upload\",\n \"name\": \"<string>\"\n }\n ],\n \"metadata\": {},\n \"prompt_context\": \"<string>\",\n \"thread_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Notion-Version", "<notion-version>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.notion.com/v1/agents/{agent_id}/chat")
.header("Notion-Version", "<notion-version>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"message\": \"<string>\",\n \"attachments\": [\n {\n \"file_upload\": {\n \"id\": \"<string>\"\n },\n \"type\": \"file_upload\",\n \"name\": \"<string>\"\n }\n ],\n \"metadata\": {},\n \"prompt_context\": \"<string>\",\n \"thread_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.notion.com/v1/agents/{agent_id}/chat")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"message\": \"<string>\",\n \"attachments\": [\n {\n \"file_upload\": {\n \"id\": \"<string>\"\n },\n \"type\": \"file_upload\",\n \"name\": \"<string>\"\n }\n ],\n \"metadata\": {},\n \"prompt_context\": \"<string>\",\n \"thread_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"object": "chat.invocation",
"agent_id": "<string>",
"thread_id": "<string>",
"invocation_id": "<string>",
"status": "pending"
}{
"object": "error",
"message": "<string>",
"code": "invalid_json",
"status": 400,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "unauthorized",
"status": 401,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "restricted_resource",
"status": 403,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "object_not_found",
"status": 404,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "row_limit_exceeded",
"status": 406,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "conflict_error",
"status": 409,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "rate_limited",
"status": 429,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "internal_server_error",
"status": 500,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "service_unavailable",
"status": 503,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "gateway_timeout",
"status": 504,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "service_overload",
"status": 529,
"additional_data": {}
}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
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.
100Show child attributes
Show child attributes
Optional caller-provided string metadata persisted with the user message. user_id is used for lifecycle correlation and does not change authorization.
Show child attributes
Show child attributes
Additional caller-provided context for the agent to consider while responding.
10000Deprecated. Use POST /v1/threads/:thread_id/messages to continue an existing thread. If not provided, a new thread will be created.