Skip to main content
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"
}
'
{
  "thread_id": "50cc9455b84d48ffad6b4c9fd41b561e",
  "conversation_id": "bc8e506e4a6f49ad",
  "agent_id": "2ec10f28abac4e01",
  "success": true,
  "response": "Hi there! How can I help you today?",
  "function_result": null
}
Call an agent to get a response to your request.

​
Endpoint

POST /call/{agent_id}

​
Parameters

​
agent_id
string
required
ID of the agent to call

​
Request Body

​
request
string
required
The prompt or request to send to the agent
​
conversation_id
string
Optional conversation ID for continuing an existing conversation

​
Response

​
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
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
required

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