POST
/
chat
curl --request POST \
  --url https://asteragents.com/api/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messages": [
    {
      "role": "<string>",
      "content": "<string>",
      "experimental_attachments": [
        {}
      ]
    }
  ],
  "agentId": 123,
  "threadId": "<string>",
  "upstreamConversationId": "<string>"
}'
{
  "400": {},
  "401": {},
  "404": {},
  "500": {},
  "messages": [
    {
      "role": "<string>",
      "content": "<string>",
      "toolCalls": [
        {}
      ],
      "toolResults": [
        {}
      ]
    }
  ],
  "X-Thread-ID": "<string>"
}

​
Authentication

​
Authorization
string
required

Bearer token for authentication

​
Body

​
messages
array
required

Array of message objects containing the conversation history

​
agentId
number
required

The ID of the AI agent to chat with

​
threadId
string

Optional UUID for the conversation thread. If not provided, a new one will be generated

​
upstreamConversationId
string

Optional UUID to link this conversation to an upstream conversation

​
Headers

​
X-Stream-Response
boolean
default:"true"

Controls whether the response is streamed. Set to false for non-streaming responses

​
Response

​
messages
array

Array of message objects containing the conversation, including the AI’s response

​
X-Thread-ID
string
required

The conversation thread ID (returned in headers)

​
Examples

​
Examples

curl -X POST https://api.example.com/chat \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Stream-Response: false" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ],
    "agentId": 123
  }'

​
Error Codes

​
401
object

Unauthorized - Invalid or missing authentication

​
404
object

Not Found - Agent or organization not found

​
400
object

Bad Request - Invalid request body

​
500
object

Internal Server Error - Unexpected error occurred