curl --request POST \
--url https://api.neoagent.io/public-api/chat/sessions/{session_id}/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"attachments": [
{
"blob_path": "<string>",
"mime": "<string>",
"alt": "<string>",
"filename": "<string>"
}
],
"client_capabilities": [
"<string>"
],
"client_message_id": "<string>",
"message": "",
"model_tier": "FAST"
}
'import requests
url = "https://api.neoagent.io/public-api/chat/sessions/{session_id}/messages"
payload = {
"attachments": [
{
"blob_path": "<string>",
"mime": "<string>",
"alt": "<string>",
"filename": "<string>"
}
],
"client_capabilities": ["<string>"],
"client_message_id": "<string>",
"message": "",
"model_tier": "FAST"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
attachments: [
{blob_path: '<string>', mime: '<string>', alt: '<string>', filename: '<string>'}
],
client_capabilities: ['<string>'],
client_message_id: '<string>',
message: '',
model_tier: 'FAST'
})
};
fetch('https://api.neoagent.io/public-api/chat/sessions/{session_id}/messages', 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.neoagent.io/public-api/chat/sessions/{session_id}/messages",
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([
'attachments' => [
[
'blob_path' => '<string>',
'mime' => '<string>',
'alt' => '<string>',
'filename' => '<string>'
]
],
'client_capabilities' => [
'<string>'
],
'client_message_id' => '<string>',
'message' => '',
'model_tier' => 'FAST'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.neoagent.io/public-api/chat/sessions/{session_id}/messages"
payload := strings.NewReader("{\n \"attachments\": [\n {\n \"blob_path\": \"<string>\",\n \"mime\": \"<string>\",\n \"alt\": \"<string>\",\n \"filename\": \"<string>\"\n }\n ],\n \"client_capabilities\": [\n \"<string>\"\n ],\n \"client_message_id\": \"<string>\",\n \"message\": \"\",\n \"model_tier\": \"FAST\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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.neoagent.io/public-api/chat/sessions/{session_id}/messages")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"attachments\": [\n {\n \"blob_path\": \"<string>\",\n \"mime\": \"<string>\",\n \"alt\": \"<string>\",\n \"filename\": \"<string>\"\n }\n ],\n \"client_capabilities\": [\n \"<string>\"\n ],\n \"client_message_id\": \"<string>\",\n \"message\": \"\",\n \"model_tier\": \"FAST\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.neoagent.io/public-api/chat/sessions/{session_id}/messages")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"attachments\": [\n {\n \"blob_path\": \"<string>\",\n \"mime\": \"<string>\",\n \"alt\": \"<string>\",\n \"filename\": \"<string>\"\n }\n ],\n \"client_capabilities\": [\n \"<string>\"\n ],\n \"client_message_id\": \"<string>\",\n \"message\": \"\",\n \"model_tier\": \"FAST\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"chat_turn_id": "<string>",
"since_cursor": "<string>",
"user_message_id": "<string>",
"audience": "MSP",
"idle_reset_minutes": 123,
"show_agent_progress_steps": true,
"trigger_mode": "<string>"
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"timings_ms": {},
"pagination": {
"has_more": true,
"next_cursor": "<string>"
},
"warnings": [
"<string>"
]
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}Append a user message + enqueue a chat turn
Persists the user message and enqueues a ChatTurnWorkflow. Returns 202 Accepted with the persisted message id + the Temporal workflow id. The agent’s streamed response is consumed via GET /chat/sessions/<id>/events. Pass client_message_id for idempotent retries — a duplicate returns 409 with the original message id and no new turn is enqueued.
The response also includes since_cursor: the SSE stream id snapshotted right before this turn was enqueued. Pass it as ?since=<since_cursor> on the very next call to /chat/sessions/<id>/events so the tail skips envelopes from prior turns on this session — skipping the cursor on a 2nd+ turn against the same session causes the tail to return the previous turn’s final state.
To include images or documents, first upload each via POST /chat/sessions/<id>/attachments/upload-url, then pass the returned blob_path values in attachments. message may be empty when at least one attachment is provided. Attachments are surfaced on later GET .../messages replays.
message holds at most 200,000 characters; a longer one is rejected with 400 and nothing is stored. Send longer text as a text/plain attachment.
A dashboard chat session’s turns run as the person who started it, so only that person’s own dashboard login may post to it; any other caller, an API key included, gets 404 chat_session_not_found and no turn is queued. The same holds for the session’s upload-url, events, stop and reset routes.
curl --request POST \
--url https://api.neoagent.io/public-api/chat/sessions/{session_id}/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"attachments": [
{
"blob_path": "<string>",
"mime": "<string>",
"alt": "<string>",
"filename": "<string>"
}
],
"client_capabilities": [
"<string>"
],
"client_message_id": "<string>",
"message": "",
"model_tier": "FAST"
}
'import requests
url = "https://api.neoagent.io/public-api/chat/sessions/{session_id}/messages"
payload = {
"attachments": [
{
"blob_path": "<string>",
"mime": "<string>",
"alt": "<string>",
"filename": "<string>"
}
],
"client_capabilities": ["<string>"],
"client_message_id": "<string>",
"message": "",
"model_tier": "FAST"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
attachments: [
{blob_path: '<string>', mime: '<string>', alt: '<string>', filename: '<string>'}
],
client_capabilities: ['<string>'],
client_message_id: '<string>',
message: '',
model_tier: 'FAST'
})
};
fetch('https://api.neoagent.io/public-api/chat/sessions/{session_id}/messages', 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.neoagent.io/public-api/chat/sessions/{session_id}/messages",
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([
'attachments' => [
[
'blob_path' => '<string>',
'mime' => '<string>',
'alt' => '<string>',
'filename' => '<string>'
]
],
'client_capabilities' => [
'<string>'
],
'client_message_id' => '<string>',
'message' => '',
'model_tier' => 'FAST'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.neoagent.io/public-api/chat/sessions/{session_id}/messages"
payload := strings.NewReader("{\n \"attachments\": [\n {\n \"blob_path\": \"<string>\",\n \"mime\": \"<string>\",\n \"alt\": \"<string>\",\n \"filename\": \"<string>\"\n }\n ],\n \"client_capabilities\": [\n \"<string>\"\n ],\n \"client_message_id\": \"<string>\",\n \"message\": \"\",\n \"model_tier\": \"FAST\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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.neoagent.io/public-api/chat/sessions/{session_id}/messages")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"attachments\": [\n {\n \"blob_path\": \"<string>\",\n \"mime\": \"<string>\",\n \"alt\": \"<string>\",\n \"filename\": \"<string>\"\n }\n ],\n \"client_capabilities\": [\n \"<string>\"\n ],\n \"client_message_id\": \"<string>\",\n \"message\": \"\",\n \"model_tier\": \"FAST\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.neoagent.io/public-api/chat/sessions/{session_id}/messages")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"attachments\": [\n {\n \"blob_path\": \"<string>\",\n \"mime\": \"<string>\",\n \"alt\": \"<string>\",\n \"filename\": \"<string>\"\n }\n ],\n \"client_capabilities\": [\n \"<string>\"\n ],\n \"client_message_id\": \"<string>\",\n \"message\": \"\",\n \"model_tier\": \"FAST\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"chat_turn_id": "<string>",
"since_cursor": "<string>",
"user_message_id": "<string>",
"audience": "MSP",
"idle_reset_minutes": 123,
"show_agent_progress_steps": true,
"trigger_mode": "<string>"
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"timings_ms": {},
"pagination": {
"has_more": true,
"next_cursor": "<string>"
},
"warnings": [
"<string>"
]
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}Authorizations
Authorization: Bearer <token> where <token> is either a neo_sk_<env>_<secret> API key (service account) or a Microsoft Entra ID access token (dashboard user).
Path Parameters
Body
Images or documents to include with this turn. Each must first be uploaded via POST /chat/sessions/<id>/attachments/upload-url. At most 6 per turn.
Show child attributes
Show child attributes
Interactive stream parts this client renders. Supported values: 'user-questions' — declare it only when you render the data-user-questions part as tappable answers, including each question's multi_select flag (tick several, then send them as one message with one pick per line — never comma-joined, because a pick can itself contain a comma) and a payload of several questions (each question's text on its own line, then its picked values one per line after '- '). 'suggested-replies' — the older event, which carries one question and rides beside the new one for every single-question payload; declare it when you render data-suggested-replies alone, and the agent keeps naming the options in its text whenever it asks several questions at once, which that event cannot carry. Declaring either stops the agent naming the options for a payload you can draw. Omit both (the default) to keep every question fully readable as plain text. 'user-questions-step-through' — declare it beside 'user-questions' when you show several questions one at a time rather than all at once; the agent may then ask any number of questions in one call, each of any length, and a payload of several questions has no cap on its options' count or length. Without it, one call holds at most 4 questions of at most 160 characters, each with at most 6 options of at most 80 characters. A one-question payload keeps the option caps either way, because it draws each option as a button.
Speed/quality tier for this turn: FAST keeps the agent's configured model; SMART escalates a single turn to a stronger model. May be flipped per turn to switch mid-conversation. Defaults to FAST.
FAST, SMART Response
Success.
202 Accepted body — the turn is enqueued, the agent's response streams via SSE.
since_cursor is the Redis-stream event id snapshotted right before this turn
was enqueued. Callers tailing /chat/sessions/<id>/events should pass it as
?since=<since_cursor> (or Last-Event-Id: <since_cursor>) so the SSE tail
starts strictly after the previous turn's terminal envelopes. Skipping this on a
2nd+ turn against the same session causes the tail to return the previous turn's
final state. May be None on the first turn of a fresh session or under Redis
failure; consumers treat None as "tail from beginning."
Show child attributes
Show child attributes
Show child attributes
Show child attributes