Trigger AI Agents via API

HUM can run any event-trigger agent in the background on work you hand it. Point a third-party webhook at a tokenized trigger URL, or assign a task to one specific agent with your API key. Either way HUM answers immediately with a run ID, the agent works with its own tools and knowledge base, and the result comes back to you.

Two ways to start a run

Both entry points share everything downstream — the same background runtime, the same run records, the same agent.run.completed webhook.

| | Inbound trigger | Direct assignment | | --- | --- | --- | | Endpoint | POST /api/triggers/inbound/<token> | POST /api/flows/<agent_id>/event-runs | | Auth | Opaque hit_… token in the URL | Organization API key | | Targets | Every agent subscribed to the event | One specific agent | | Result | Signed callback and/or polling | Polling (plus the org-wide webhook) | | Best for | Third-party webhooks: GitHub, your CRM, Zapier | Scripts, backend jobs, and AI assistants over MCP |

Use a trigger when an external system owns the event and you want fan-out. Use direct assignment when you already know which agent should do the work.

The request/response loop

1. 1.You POST JSON to your trigger URL. The body becomes the agent's working context.
2. 2.HUM responds 202 immediately with a runs array — one run_id (and status_url) per agent the event started.
3. 3.The agent works in the background: reading your payload, looking things up in the knowledge base, and calling the HTTP tools you've enabled for it.
4. 4.The result comes back — HUM POSTs a signed agent.run.completed payload to your callback URL, and/or you poll the status_url until status leaves queued.

Creating a trigger

Under Settings → Integrations → Inbound triggers, create a trigger with a name and an event type (normalized to external.<name> so it can never collide with HUM's built-in events). You get back, exactly once:

• the trigger URL containing an opaque hit_… bearer token, and
• a callback secret (hcs_…) used to sign result callbacks.

Both are rotatable at any time. Then open your agent under AI Agents, set its trigger to Event, and subscribe it to your new external.* event.

Firing the trigger

POST any JSON object to the trigger URL. Everything in the body is handed to the agent as context, plus a _trigger block identifying which trigger fired. Two fields are reserved:

• _callback — a per-request callback override: {"_callback": {"url": "https://example.com/hook"}} (or a plain string). Must be a public https:// URL. It replaces the trigger's default callback URL for this request only and is stripped before the agent sees the payload.
• id — if present, used for idempotency: redelivering the same payload with the same id within an hour returns the original run's result instead of running the agent again.

The 202 response lists each run started: {"ok": true, "event_type": "external.github.issue", "runs": [{"agent_id": "…", "run_id": "…", "status_url": "…"}]}. An empty runs array means no agent is subscribed to that event yet.

Receiving the result callback

Set a default callback URL on the trigger (or pass _callback per request). When each run finishes, HUM POSTs a JSON body shaped exactly like an outbound webhook delivery: {"type": "agent.run.completed", "org_id": "…", "delivered_at": "…", "data": {…}}.

The data object carries the outcome: run_id, agent_id, agent_name, event_type, status (completed, failed, no_op, or tool_loop_exceeded), the agent's final output text, a tool_calls summary (name, status, latency — not arguments), token usage, latency_ms, and error when something went wrong. Deduplicated deliveries include deduped: true and the original_run_id.

Every callback is signed: the X-HUM-Signature header contains sha256=<hex> — an HMAC-SHA256 of the raw request body using your trigger's callback secret. Verify it before trusting the payload, exactly as you would an outbound webhook. X-HUM-Run-ID and X-HUM-Trigger-ID headers make correlation easy.

Polling instead of callbacks

Can't receive webhooks (CLI scripts, cron jobs, locked-down networks)? GET the status_url from the 202 response — it's the trigger URL plus /runs/<run_id>, authenticated by the same token. While the agent is working, status is queued; once finished, the response includes the full output, tool-call summary, usage, and (if a callback was configured) its delivery outcome.

Assigning a task directly

POST to the agent's runs endpoint with an API key. input can be plain language or a structured object and must serialize to at most 64 KB; the response comes back immediately with a run ID rather than waiting for the agent to finish.

curl -X POST https://hum-api.bluehive.com/api/flows/<agent_id>/event-runs \
  -H "Authorization: Bearer $HUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Summarize yesterday'\''s missed calls", "task_id": "daily-2026-07-25"}'

{
  "ok": true,
  "run_id": "5f1c…",
  "agent_id": "…",
  "status": "queued",
  "done": false,
  "deduplicated": false,
  "status_url": "https://hum-api.bluehive.com/api/flows/<agent_id>/event-runs/5f1c…"
}

Then poll status_url (or GET /api/flows/<agent_id>/event-runs/<run_id>) until done is true:

{
  "run_id": "5f1c…",
  "status": "completed",
  "done": true,
  "output": "Three missed calls yesterday, all from existing patients…",
  "tool_calls": [{ "name": "lookup_knowledge", "status": "ok", "latency_ms": 412 }],
  "usage": { "input_tokens": 1204, "output_tokens": 287, "total_tokens": 1491 },
  "latency_ms": 5310,
  "error": null
}

done is false only while status is queued; once it settles, status is completed, failed, no_op, or tool_loop_exceeded. The target agent's trigger must be set to Event; assigning a task to a voice or SMS agent returns 404.

Retrying safely

Pass task_id and retries stop being dangerous. For one hour after a task is first submitted under a given key, replaying that key returns the same run — whether it is still working or already finished. The agent never does the work twice, so its tool side effects don't repeat. The reply carries "deduplicated": true and the original run_id, so polling status_url gives you the original result rather than an empty record.

That holds for a retry sent while the first run is still working, and for two requests racing each other with the same key. Two details worth knowing:

• The hour runs from submission, not from when the run finished. Agent runs are capped at a handful of model turns, so in practice they settle seconds after they start.
• Runs that end in failed or tool_loop_exceeded release the key immediately, so retrying after a genuine failure starts a real second attempt instead of replaying a dead end.

Direct assignment has no per-request callback — poll the run, or subscribe an outbound webhook to agent.run.completed for org-wide delivery. GET /api/flows/<agent_id>/event-runs lists an agent's recent runs.

tool_calls reports the name, outcome, and latency of each tool the agent used. The arguments it passed and the raw responses it received are never returned — they stay inside HUM.

AI assistants connected over MCP call this through the assign_agent_task and get_agent_run tools.

What you can build with it

• Ticket triage — point a GitHub or Redmine webhook at your trigger; the agent reads each new issue, checks your knowledge base, drafts a response or severity assessment, and posts it back through an HTTP tool or the callback.
• CRM enrichment — your CRM fires the trigger when a lead is created; the agent researches, scores, and writes the enrichment back, and your CRM gets the structured result in the callback.
• Order and shipping updates — your commerce platform fires the trigger on shipment; the agent composes and sends the customer SMS, and your system records the result.
• Zapier / n8n / Make — use an HTTP action to fire the trigger and a webhook trigger to catch the callback; the run ID ties the two ends of the flow together.
• Nightly jobs — a cron script POSTs a work batch, then polls the status URL until done — no inbound connectivity required.
• Assistant-driven work — connect Copilot or Claude over MCP and hand an agent a task in plain language: "ask my triage agent to summarize this week's escalations," then let the assistant poll and report back.

Watching runs and staying in the loop

Each trigger's Runs view in Settings shows recent runs with status, output preview, latency, and callback delivery outcome. For org-wide observability, subscribe an outbound webhook to the agent.run.completed event — it fires for *every* event-agent run, whether started by API, by a HUM event, or on a schedule. (Agents themselves can't subscribe to it, so loops are impossible.)

Security model

• Trigger URLs authenticate with the opaque token in the path — treat it like a credential and rotate it if exposed.
• Callback URLs must be public https:// endpoints; HUM refuses private and internal addresses.
• Callbacks are HMAC-signed with a dedicated per-trigger secret, rotatable independently of the token.
• Request bodies are capped at 64 KB, and callback outputs are clamped to keep deliveries lean — poll the status URL for the full text.