Call Agent

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>"
}

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

X-API-Key

string

header

required

API key provided by Headless Agents

Path Parameters

agent_id

string

required

ID of the agent to call

Body

application/json

request

string

required

The prompt or request to send to the agent

conversation_id

string

Optional conversation ID for continuing an existing conversation

Response

Successful response from agent

thread_id

string

required

Unique identifier for this interaction thread

conversation_id

string

required

Identifier for the conversation

agent_id

string

required

ID of the agent that was called

success

boolean

required

Whether the call was successful

response

string

required

The agent's response text

function_result

object | null

required

Optional structured data returned by the agent, null if no structured data

API Documentation

Endpoints

Endpoint

Parameters

Request Body

Response

Authorizations

Path Parameters

Body

Response

​Endpoint

​Parameters

​Request Body

​Response

Authorizations

Path Parameters

Body

Response

Endpoint

Parameters

Request Body

Response