Skip to main content
Use the public API when your app needs to start a Hive Agent run outside the dashboard. The API starts the run asynchronously, returns identifiers immediately, and sends a signed callback when the run finishes. Hive Agent invocation does not stream and does not wait for the final answer in the HTTP response. Open Logs to inspect status, trace, costs, node output, partial results, callback attempts, and the final response.

​
Endpoint

POST /v1/stream/hive_agent/invoke
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

​
Request body

{
  "hive_agent": "agent_task_uuid",
  "objective": "Research competitors and summarize verified findings",
  "sources": {
    "website_urls": [],
    "asset_ids": [],
    "knowledge_base_ids": [],
    "knowledge_base_item_ids": []
  },
  "metadata": {},
  "async": {
    "enabled": true,
    "callback_url": "https://example.com/hive-agent-callback"
  }
}
hive_agent is the Hive Agent ID from the dashboard. The API key must belong to the same workspace as the Hive Agent. Only customer-created Hive Agents in your workspace can be invoked through this endpoint. objective should be specific enough for the planner to create useful work nodes. sources is optional but recommended when the run needs grounded context. Pass website URLs, asset IDs, knowledge base IDs, or knowledge base item IDs that already exist in the workspace. Use GET /v1/public/workspaces/{workspace_id}/knowledge_bases to list knowledge bases, GET /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}/items to list items, and GET /v1/public/workspaces/{workspace_id}/assets to list assets. Upload a file with POST /v1/public/workspaces/{workspace_id}/assets before passing its asset.id in sources.asset_ids. metadata is optional caller metadata for your own correlation, such as a customer ID or job ID. async.callback_url is required. Fetch Hive sends the terminal callback to this HTTPS URL after the run completes, fails, or is cancelled. async.enabled must be true.

​
Response

Fetch Hive returns 202 Accepted when the run is queued for execution. 
{
  "run_id": "agent_task_run_uuid",
  "request_id": "req_018c9f8ea1b2c3d4e5f6g7h8i9j0k1l2",
  "status": "pending",
  "webhook_secret": "whsec_..."
}
Save request_id if you need to find the run later in logs. Store webhook_secret so your callback receiver can verify X-Fetch-Hive-Signature. The initial status is usually pending; the runtime updates status as source preparation, planning, execution, verification, and composition continue.

​
cURL example

curl https://api.fetchhive.com/v1/stream/hive_agent/invoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hive_agent": "agent_task_uuid",
    "objective": "Research competitors and summarize verified findings",
    "sources": {
      "website_urls": ["https://example.com"],
      "asset_ids": [],
      "knowledge_base_ids": [],
      "knowledge_base_item_ids": []
    },
    "metadata": {
      "customer_id": "cus_123"
    },
    "async": {
      "enabled": true,
      "callback_url": "https://example.com/hive-agent-callback"
    }
  }'

​
Callback payload

Fetch Hive sends a signed JSON payload to async.callback_url when the run reaches a terminal status. The event_type is one of hive_agent.completed, hive_agent.failed, or hive_agent.cancelled. 
{
  "event_type": "hive_agent.completed",
  "request_id": "req_018c9f8ea1b2c3d4e5f6g7h8i9j0k1l2",
  "data": {
    "run_id": "agent_task_run_uuid",
    "hive_agent_id": "agent_task_uuid",
    "hive_agent_name": "Competitor Research",
    "status": "completed",
    "success": true,
    "objective": "Research competitors and summarize verified findings",
    "final_response": {},
    "error_message": null,
    "metadata": {
      "customer_id": "cus_123"
    },
    "sources": []
  }
}
Callbacks use the same signature headers as other Fetch Hive outbound webhooks: X-Fetch-Hive-Signature, X-Fetch-Hive-Timestamp, and X-Fetch-Hive-Webhook-Id. See Callback Delivery and Webhook Triggers for verification guidance.

​
Find results

Open Hive Agents > Logs and search by Hive Agent name, objective, status, or request ID. Open the run to review node work, verifier feedback, source handling, budget events, trace spans, and the final response. The run detail also shows callback delivery attempts and retry state. There is no synchronous wait or streaming option for Hive Agent public invocation in this version.