Saltar al contenido principal
Usa la API publica cuando tu app necesite iniciar una ejecucion de Hive Agent fuera del dashboard. La API inicia la ejecucion de forma asincrona, devuelve identificadores de inmediato y envia un callback firmado cuando finaliza. La invocacion de Hive Agent no transmite eventos y no espera la respuesta final en la respuesta HTTP. Abre Registros para revisar estado, traza, costes, salida de nodos, resultados parciales, intentos de callback y respuesta final.

​
Endpoint

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

​
Cuerpo de la solicitud

{
  "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 es el ID del Hive Agent en el dashboard. La API key debe pertenecer al mismo workspace que el Hive Agent. Solo se pueden invocar por este endpoint los Hive Agents creados por el cliente en tu workspace. objective debe ser lo bastante especifico para que el planificador cree nodos de trabajo utiles. sources es opcional, pero se recomienda cuando la ejecucion necesita contexto fundamentado. Pasa URLs de sitios, IDs de assets, IDs de knowledge bases o IDs de items de knowledge base que ya existan en el workspace. Usa GET /v1/public/workspaces/{workspace_id}/knowledge_bases para listar knowledge bases, GET /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}/items para listar items y GET /v1/public/workspaces/{workspace_id}/assets para listar assets. Sube un archivo con POST /v1/public/workspaces/{workspace_id}/assets antes de pasar su asset.id en sources.asset_ids. metadata es opcional y sirve para tu propia correlacion, como un customer ID o job ID. async.callback_url es obligatorio. Fetch Hive envia el callback terminal a esta URL HTTPS cuando la ejecucion se completa, falla o se cancela. async.enabled debe ser true.

​
Respuesta

Fetch Hive devuelve 202 Accepted cuando la ejecucion queda en cola para ejecutarse. 
{
  "run_id": "agent_task_run_uuid",
  "request_id": "req_018c9f8ea1b2c3d4e5f6g7h8i9j0k1l2",
  "status": "pending",
  "webhook_secret": "whsec_..."
}
Guarda request_id si necesitas encontrar la ejecucion luego en logs. Guarda webhook_secret para que tu receptor pueda verificar X-Fetch-Hive-Signature. El estado inicial normalmente es pending; el runtime actualiza el estado mientras prepara fuentes, planifica, ejecuta, verifica y compone.

​
Ejemplo cURL

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"
    }
  }'

​
Payload del callback

Fetch Hive envia un payload JSON firmado a async.callback_url cuando la ejecucion llega a un estado terminal. event_type es hive_agent.completed, hive_agent.failed o 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": []
  }
}
Los callbacks usan los mismos headers de firma que otros webhooks salientes de Fetch Hive: X-Fetch-Hive-Signature, X-Fetch-Hive-Timestamp y X-Fetch-Hive-Webhook-Id. Consulta Callback Delivery and Webhook Triggers para la verificacion.

​
Encontrar resultados

Abre Hive Agents > Logs y busca por nombre de Hive Agent, objetivo, estado o request ID. Abre la ejecucion para revisar trabajo de nodos, feedback del verificador, manejo de fuentes, eventos de presupuesto, spans de traza y respuesta final. El detalle de la ejecucion tambien muestra intentos de callback y estado de reintento. En esta version no hay espera sincrona ni opcion de streaming para la invocacion publica de Hive Agents.