Chat with an AI Agent

curl --request POST \
  --url https://asteragents.com/api/chat \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "messages": [
    {
      "role": "<string>",
      "parts": [
        {
          "type": "<string>",
          "text": "<string>"
        }
      ]
    }
  ],
  "agentId": 123,
  "threadId": "<string>",
  "upstreamConversationId": "<string>"
}
'

import requests

url = "https://asteragents.com/api/chat"

payload = {
    "messages": [
        {
            "role": "<string>",
            "parts": [
                {
                    "type": "<string>",
                    "text": "<string>"
                }
            ]
        }
    ],
    "agentId": 123,
    "threadId": "<string>",
    "upstreamConversationId": "<string>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    messages: [{role: '<string>', parts: [{type: '<string>', text: '<string>'}]}],
    agentId: 123,
    threadId: '<string>',
    upstreamConversationId: '<string>'
  })
};

fetch('https://asteragents.com/api/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://asteragents.com/api/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([
    'messages' => [
        [
                'role' => '<string>',
                'parts' => [
                                [
                                                                'type' => '<string>',
                                                                'text' => '<string>'
                                ]
                ]
        ]
    ],
    'agentId' => 123,
    'threadId' => '<string>',
    'upstreamConversationId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "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://asteragents.com/api/chat"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"role\": \"<string>\",\n      \"parts\": [\n        {\n          \"type\": \"<string>\",\n          \"text\": \"<string>\"\n        }\n      ]\n    }\n  ],\n  \"agentId\": 123,\n  \"threadId\": \"<string>\",\n  \"upstreamConversationId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	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://asteragents.com/api/chat")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"role\": \"<string>\",\n      \"parts\": [\n        {\n          \"type\": \"<string>\",\n          \"text\": \"<string>\"\n        }\n      ]\n    }\n  ],\n  \"agentId\": 123,\n  \"threadId\": \"<string>\",\n  \"upstreamConversationId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://asteragents.com/api/chat")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"role\": \"<string>\",\n      \"parts\": [\n        {\n          \"type\": \"<string>\",\n          \"text\": \"<string>\"\n        }\n      ]\n    }\n  ],\n  \"agentId\": 123,\n  \"threadId\": \"<string>\",\n  \"upstreamConversationId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "400": {},
  "401": {},
  "404": {},
  "500": {},
  "messages": [
    {
      "role": "<string>",
      "parts": [
        {
          "type": "<string>",
          "text": "<string>"
        }
      ],
      "toolCalls": [
        {}
      ]
    }
  ],
  "X-Thread-ID": "<string>"
}

POST

chat

Chat with an AI Agent

curl --request POST \
  --url https://asteragents.com/api/chat \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "messages": [
    {
      "role": "<string>",
      "parts": [
        {
          "type": "<string>",
          "text": "<string>"
        }
      ]
    }
  ],
  "agentId": 123,
  "threadId": "<string>",
  "upstreamConversationId": "<string>"
}
'

import requests

url = "https://asteragents.com/api/chat"

payload = {
    "messages": [
        {
            "role": "<string>",
            "parts": [
                {
                    "type": "<string>",
                    "text": "<string>"
                }
            ]
        }
    ],
    "agentId": 123,
    "threadId": "<string>",
    "upstreamConversationId": "<string>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    messages: [{role: '<string>', parts: [{type: '<string>', text: '<string>'}]}],
    agentId: 123,
    threadId: '<string>',
    upstreamConversationId: '<string>'
  })
};

fetch('https://asteragents.com/api/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://asteragents.com/api/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([
    'messages' => [
        [
                'role' => '<string>',
                'parts' => [
                                [
                                                                'type' => '<string>',
                                                                'text' => '<string>'
                                ]
                ]
        ]
    ],
    'agentId' => 123,
    'threadId' => '<string>',
    'upstreamConversationId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "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://asteragents.com/api/chat"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"role\": \"<string>\",\n      \"parts\": [\n        {\n          \"type\": \"<string>\",\n          \"text\": \"<string>\"\n        }\n      ]\n    }\n  ],\n  \"agentId\": 123,\n  \"threadId\": \"<string>\",\n  \"upstreamConversationId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	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://asteragents.com/api/chat")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"role\": \"<string>\",\n      \"parts\": [\n        {\n          \"type\": \"<string>\",\n          \"text\": \"<string>\"\n        }\n      ]\n    }\n  ],\n  \"agentId\": 123,\n  \"threadId\": \"<string>\",\n  \"upstreamConversationId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://asteragents.com/api/chat")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"role\": \"<string>\",\n      \"parts\": [\n        {\n          \"type\": \"<string>\",\n          \"text\": \"<string>\"\n        }\n      ]\n    }\n  ],\n  \"agentId\": 123,\n  \"threadId\": \"<string>\",\n  \"upstreamConversationId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "400": {},
  "401": {},
  "404": {},
  "500": {},
  "messages": [
    {
      "role": "<string>",
      "parts": [
        {
          "type": "<string>",
          "text": "<string>"
        }
      ],
      "toolCalls": [
        {}
      ]
    }
  ],
  "X-Thread-ID": "<string>"
}

Authentication

string

required

Bearer token for authentication

Body

array

required

Array of message objects containing the conversation history

Show Message Object

string

required

The role of the message sender (user or assistant)

array

required

Array of content parts for the message

Show Part Object

string

required

The type of part (text, file, etc.)

string

The text content (required when type is text)

number

required

The ID of the AI agent to chat with

string

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

string

Optional UUID to link this conversation to an upstream conversation

Headers

boolean

default:"true"

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

Response

array

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

Show Message Object

string

The role of the message sender (user or assistant)

array

Array of content parts for the message

Show Part Object

string

The type of part (text, tool-invocation, tool-result, etc.)

string

The text content (when type is text)

array

Optional array of tool calls made by the assistant

string

required

The conversation thread ID (returned in headers)

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",
        "parts": [{"type": "text", "text": "Hello, how are you?"}]
      }
    ],
    "agentId": 123
  }'

import requests

url = "https://api.example.com/chat"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
    "X-Stream-Response": "false"
}
data = {
    "messages": [
        {
            "role": "user",
            "parts": [{"type": "text", "text": "Hello, how are you?"}]
        }
    ],
    "agentId": 123
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const response = await fetch('https://api.example.com/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
    'X-Stream-Response': 'false'
  },
  body: JSON.stringify({
    messages: [
      {
        role: 'user',
        parts: [{ type: 'text', text: 'Hello, how are you?' }]
      }
    ],
    agentId: 123
  })
});

const data = await response.json();

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/chat",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_TOKEN",
    "Content-Type: application/json",
    "X-Stream-Response: false"
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "messages" => [
      [
        "role" => "user",
        "parts" => [["type" => "text", "text" => "Hello, how are you?"]]
      ]
    ],
    "agentId" => 123
  ])
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);

{
  "messages": [
    {
      "role": "user",
      "parts": [{"type": "text", "text": "Hello, how are you?"}]
    },
    {
      "role": "assistant",
      "parts": [{"type": "text", "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"}]
    }
  ]
}

Error Codes

object

Unauthorized - Invalid or missing authentication

object

Not Found - Agent or organization not found

object

Bad Request - Invalid request body

object

Internal Server Error - Unexpected error occurred

API Documentation

Admin API

Files API

Agents API

Tools API

Agent Tags API

Knowledge Bases API

Skills API

Conversations API

Scheduled Tasks API

Other Endpoints

Legacy Endpoints (Deprecated)

Chat with an AI Agent

Authentication

Body

Headers

Response

Examples

Examples

Error Codes

​Authentication

​Body

​Headers

​Response

​Examples

​Examples

​Error Codes

Authentication

Body

Headers

Response

Examples

Examples

Error Codes