POST
/
chat
Chat with an AI Agent
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