Call an agent
curl --request POST \
--url https://api.headlessagents.ai/call/{agent_id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"request": "What is the weather like in San Francisco?",
"conversation_id": "bc8e506e4a6f49ad"
}
'import requests
url = "https://api.headlessagents.ai/call/{agent_id}"
payload = {
"request": "What is the weather like in San Francisco?",
"conversation_id": "bc8e506e4a6f49ad"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
request: 'What is the weather like in San Francisco?',
conversation_id: 'bc8e506e4a6f49ad'
})
};
fetch('https://api.headlessagents.ai/call/{agent_id}', 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.headlessagents.ai/call/{agent_id}",
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([
'request' => 'What is the weather like in San Francisco?',
'conversation_id' => 'bc8e506e4a6f49ad'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$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.headlessagents.ai/call/{agent_id}"
payload := strings.NewReader("{\n \"request\": \"What is the weather like in San Francisco?\",\n \"conversation_id\": \"bc8e506e4a6f49ad\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
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.headlessagents.ai/call/{agent_id}")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"request\": \"What is the weather like in San Francisco?\",\n \"conversation_id\": \"bc8e506e4a6f49ad\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.headlessagents.ai/call/{agent_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"request\": \"What is the weather like in San Francisco?\",\n \"conversation_id\": \"bc8e506e4a6f49ad\"\n}"
response = http.request(request)
puts response.read_body{
"thread_id": "50cc9455b84d48ffad6b4c9fd41b561e",
"conversation_id": "bc8e506e4a6f49ad",
"agent_id": "2ec10f28abac4e01",
"success": true,
"response": "Hi there! How can I help you today?",
"function_result": null
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}Endpoints
Call Agent
Send a request to an agent and get their response
POST
/
call
/
{agent_id}
Call an agent
curl --request POST \
--url https://api.headlessagents.ai/call/{agent_id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"request": "What is the weather like in San Francisco?",
"conversation_id": "bc8e506e4a6f49ad"
}
'import requests
url = "https://api.headlessagents.ai/call/{agent_id}"
payload = {
"request": "What is the weather like in San Francisco?",
"conversation_id": "bc8e506e4a6f49ad"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
request: 'What is the weather like in San Francisco?',
conversation_id: 'bc8e506e4a6f49ad'
})
};
fetch('https://api.headlessagents.ai/call/{agent_id}', 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.headlessagents.ai/call/{agent_id}",
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([
'request' => 'What is the weather like in San Francisco?',
'conversation_id' => 'bc8e506e4a6f49ad'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$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.headlessagents.ai/call/{agent_id}"
payload := strings.NewReader("{\n \"request\": \"What is the weather like in San Francisco?\",\n \"conversation_id\": \"bc8e506e4a6f49ad\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
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.headlessagents.ai/call/{agent_id}")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"request\": \"What is the weather like in San Francisco?\",\n \"conversation_id\": \"bc8e506e4a6f49ad\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.headlessagents.ai/call/{agent_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"request\": \"What is the weather like in San Francisco?\",\n \"conversation_id\": \"bc8e506e4a6f49ad\"\n}"
response = http.request(request)
puts response.read_body{
"thread_id": "50cc9455b84d48ffad6b4c9fd41b561e",
"conversation_id": "bc8e506e4a6f49ad",
"agent_id": "2ec10f28abac4e01",
"success": true,
"response": "Hi there! How can I help you today?",
"function_result": null
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}Call an agent to get a response to your request.
Endpoint
POST /call/{agent_id}
Parameters
string
required
ID of the agent to call
Request Body
string
required
The prompt or request to send to the agent
string
Optional conversation ID for continuing an existing conversation
Response
string
required
Unique identifier for this interaction thread
string
required
Identifier for the conversation
string
required
ID of the agent that was called
boolean
required
Whether the call was successful
string
required
The agent’s response text
object
Optional structured data returned by the agent, null if no structured data
{
"thread_id": "50cc9455b84d48ffad6b4c9fd41b561e",
"conversation_id": "bc8e506e4a6f49ad",
"agent_id": "2ec10f28abac4e01",
"success": true,
"response": "I am a greeting assistant designed to help with welcoming users...",
"function_result": null
}
Authorizations
API key provided by Headless Agents
Path Parameters
ID of the agent to call
Body
application/json
Response
Successful response from agent
Unique identifier for this interaction thread
Identifier for the conversation
ID of the agent that was called
Whether the call was successful
The agent's response text
Optional structured data returned by the agent, null if no structured data