Send a message and stream the reply as server-sent events

curl --request POST \
  --url https://api.chattler.ai/v1/agents/{agent_id}/chat/stream \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "external_user_id": "<string>",
  "message": "<string>"
}
'

import requests

url = "https://api.chattler.ai/v1/agents/{agent_id}/chat/stream"

payload = {
    "external_user_id": "<string>",
    "message": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({external_user_id: '<string>', message: '<string>'})
};

fetch('https://api.chattler.ai/v1/agents/{agent_id}/chat/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

Chat

Send a message and stream the reply as server-sent events

The streaming form of the chat endpoint. Request body, authentication, full permission, Idempotency-Key, conversation rules, billing, and error codes are identical to POST /v1/agents/{agent_id}/chat; only the transport differs. The response is text/event-stream with named events, each carrying a JSON data payload:

response.created: {"request_id", "conversation_id"} as soon as the conversation is resolved
response.output_text.delta: {"delta": "..."} for every piece of answer text as the model produces it
response.completed: the same object the synchronous endpoint returns (request_id, conversation_id, persisted message, usage); always the last event of a successful stream
error: {"code", "message", "request_id"}, the same error object as the JSON envelope; always the last event of a failed stream

Example Request

curl -N -X POST "/v1/agents/{agent_id}/chat/stream" \
  -H "Authorization: Bearer cht_live_{key_id}.{secret}" \
  -H "Idempotency-Key: 5b2f0d4e-1c0e-4c2b-9a5e-3d8a2f6b1c77" \
  -H "Content-Type: application/json" \
  -d '{"external_user_id": "customer-123", "message": "I want to know the price"}'

Notes

Failures before the stream is established (invalid key, validation, idempotency_conflict, conversation_busy, disabled agent, rate limit) are answered as a normal JSON error envelope with the matching HTTP status, not as a stream.
Once headers are sent the HTTP status is already 200; a failure after that point (for example insufficient_balance or internal_error) arrives as the error event.
The reply keeps being produced and stored even if the client disconnects mid-stream, and no second reply or charge results from retrying: a retry with the same Idempotency-Key streams response.created followed directly by response.completed with the stored result, without replaying the deltas.
Reasoning text and tool activity are never part of the stream; response.completed always carries the full final text, so a client that missed deltas can reconcile from it.

POST

agents

{agent_id}

chat

stream

Send a message and stream the reply as server-sent events

curl --request POST \
  --url https://api.chattler.ai/v1/agents/{agent_id}/chat/stream \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "external_user_id": "<string>",
  "message": "<string>"
}
'

import requests

url = "https://api.chattler.ai/v1/agents/{agent_id}/chat/stream"

payload = {
    "external_user_id": "<string>",
    "message": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({external_user_id: '<string>', message: '<string>'})
};

fetch('https://api.chattler.ai/v1/agents/{agent_id}/chat/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Agent API key: Authorization: Bearer cht_live_<key_id>.

Headers

Idempotency-Key

string

required

Client-chosen value, 1-255 characters, unique per logical request; a retry with the same value and body returns the stored result

Required string length: 1 - 255

Path Parameters

agent_id

string

required

Body

application/json

Text-only chat input; attachments are outside this release, so any extra field is a validation error rather than silently ignored.

external_user_id

string

required

Stable id of the end user on the caller's side

Required string length: 1 - 255

message

string

required

Minimum string length: 1

Response

SSE stream: response.created, response.output_text.delta*, then response.completed or error

API Reference

Chat

Conversations

Send a message and stream the reply as server-sent events

Example Request

Notes

Authorizations

Headers

Path Parameters

Body

Response