API reference

Agents

Trigger a goal-driven agent to run on demand from your own backend. The run is detached — the call returns immediately, and the agent works its goal in the background. Read the outcome later as a conversation.

Agents vs. chat. Use this endpoint for agent bots (bot_type="agent") — the goal-driven, multi-step runners described in Scheduled agents. For a turn-by-turn conversational reply from a chatbot, use the Chat API instead.

Trigger an agent

Method & pathAbility
POST /api/v1/agents/{id}/triggeragents:trigger

{id} is the agent's bot id. The bot must be bot_type="agent"; triggering a chatbot is rejected. The agent runs with its own configured goal, prompt, tools, and output settings — see the bot object (agent_goal, max_iterations, timeout_seconds, output_config).

curl -X POST https://app.hania.ai/api/v1/agents/b1f2c3d4-…/trigger \
  -H "Authorization: Bearer $HANIA_API_KEY"

Response

A successful trigger returns 202 Accepted — the run has been accepted and started, not finished:

{
  "success": true,
  "data": {
    "conversation_id": "c9a8b7c6-…",
    "status": "accepted"
  }
}

Persist the returned conversation_id. Because the run is detached, the result isn't in this response — poll the conversation for progress and the final outcome.

Reading the outcome

An agent run surfaces as a conversation with channel=agent. Fetch it with conversations:read:

  • GET /api/v1/conversations/{conversation_id} — messages and final output.
  • GET /api/v1/conversations/{conversation_id}/trace — the step-by-step execution trace (model turns and tool calls), useful for debugging a run.
← Previous
Calls