Chat & tasks

There are two ways to give an agent work through the API:

	POST /api/agents/{name}/chat	POST /api/agents/{name}/task
Context	Continues the agent’s ongoing conversation	Stateless — a fresh run each time
Best for	Conversational use, assistants	Automations, pipelines, parallel work
Async	—	async_mode: true

Chat

curl -X POST https://acme.exohuman.cc/api/agents/sales-assistant/chat \
  -H "Authorization: Bearer $EXOHUMAN_API_KEY" -H 'Content-Type: application/json' \
  -d '{"message":"Summarise yesterday’s new leads."}'

The body takes message and an optional model override. Files can be attached as files (name, MIME type and base64 content). The agent must be running; if it is busy, the message waits its turn.

Endpoint	Method	Description
/api/agents/{name}/chat	POST	Send a message
/api/agents/{name}/chat/history	GET / DELETE	Current conversation; reset it (owner/admin)
/api/agents/{name}/chat/session	GET	Current session and context usage
/api/agents/{name}/chat/sessions	GET	List sessions
/api/agents/{name}/chat/sessions/{id}	GET	One session with messages

Tasks

curl -X POST https://acme.exohuman.cc/api/agents/research-analyst/task \
  -H "Authorization: Bearer $EXOHUMAN_API_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: weekly-report-2026-w45' \
  -d '{"message":"Compile the weekly competitor report.","async_mode":true}'
# → {"status":"accepted","execution_id":"…","async_mode":true}

Useful fields:

Field	Purpose
message	The task (required)
model	Model override for this run
async_mode	Return immediately with an execution_id
system_prompt	Extra instructions appended for this run
allowed_tools	Restrict the tools available
max_turns	Cap agentic turns
files	Attachments

A synchronous call holds the connection until the run finishes and returns the response with an execution_id receipt. For long work, use async_mode and poll.

Executions

Endpoint	Method	Description
/api/agents/{name}/executions	GET	List the agent’s executions
/api/agents/{name}/executions/{id}	GET	Status, response and cost — the polling target
/api/agents/{name}/executions/{id}/log	GET	Full transcript with tool calls
/api/agents/{name}/executions/{id}/stream	GET	Live log (server-sent events)
/api/agents/{name}/executions/running	GET	Currently running executions
/api/agents/{name}/executions/{id}/terminate	POST	Stop a running or queued execution

curl -s https://acme.exohuman.cc/api/agents/research-analyst/executions/$EXEC_ID \
  -H "Authorization: Bearer $EXOHUMAN_API_KEY" | jq '{status, cost}'

A failed run is not retried automatically. To retry, send the request again with a new idempotency key (or none).

Parallel work

POST /api/agents/{name}/fan-out dispatches several tasks in parallel to an agent and GET /api/agents/{name}/fan-out/{fan_out_id} polls the batch. Parallel capacity is bounded by the agent’s settings and your plan.

Public chat

Agents shared through a public link are reachable without an account at /api/public/chat/{token}, subject to the agent’s access policy.