> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoke

> Start Hive Agent runs from the public API with callback delivery

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](./logs) to inspect status, trace, costs, node output, partial results, callback attempts, and the final response.

## Endpoint

```http theme={null}
POST /v1/stream/hive_agent/invoke
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Request body

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

```bash theme={null}
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`.

```json theme={null}
{
  "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](../workflows/async-and-webhooks) 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.