Saltar al contenido principal

​
Ejecutar con API

Usa el endpoint público de invocación de flujos de trabajo cuando quieras ejecutar un deployment de flujo de trabajo desde tu propia aplicación o servicio. Crea un deployment de flujo de trabajo en el dashboard, elige una variante y luego usa los detalles del deployment en tu solicitud. Si un producto externo necesita iniciar un flujo de trabajo enviando un webhook directamente a Fetch Hive, usa la URL de disparador de webhook desde el asistente del deployment en su lugar. Ese flujo usa X-Fetch-Hive-Webhook-Secret en lugar de una clave de API del workspace. Consulta Entrega por callback y disparadores de webhook.

​
Autenticación

Authorization: Bearer YOUR_API_KEY
Consulta API Keys para saber cómo crear y administrar claves.

​
Endpoint

POST https://api.fetchhive.com/v1/workflow/invoke Antes de llamar a este endpoint, crea un deployment y una variante de flujo de trabajo desde el editor de flujos de trabajo. Consulta Publicación y versionado para ese flujo de la interfaz.

​
Solicitud

Usa esta forma de solicitud:
CampoTipoRequeridoDescripción
deploymentstringSíLa clave del deployment del flujo de trabajo
variantstringSíLa variante de deployment que quieres ejecutar
inputsobjectNoPares clave-valor para las variables definidas en el paso Start del flujo de trabajo
asyncobjectNoAjustes de entrega por callback. Consulta Entrega por callback y disparadores de webhook
metadataobjectNoMetadata plana definida por quien llama, para auditoría y filtrado de registros. No se usa como entrada del flujo de trabajo.
Los valores de inputs deben coincidir con los tipos de entrada de Start del flujo de trabajo. Las entradas de texto aceptan cadenas. Las entradas de tipo array deben ser arreglos JSON nativos, por ejemplo "companies": [{"name":"Fetch Hive"}]. Los arreglos se preservan como arreglos en las variables del flujo de trabajo y en los registros. metadata debe ser plana y solo escalar: cadenas, números, booleanos o null. Los objetos anidados y los arreglos devuelven un error de validación antes de que comience la ejecución. Si incluyes async, usa estos campos anidados:
CampoTipoRequeridoDescripción
async.enabledbooleanSíConfigúralo en true para devolver respuesta inmediatamente y entregar el resultado más tarde mediante callback firmado
async.callback_urlstringSí cuando la entrega por callback está habilitadaLa URL de callback a la que Fetch Hive debe llamar cuando la ejecución termine
Los flujos de trabajo que contienen un paso Human in the Loop deben usar entrega por callback. Configura async.enabled en true y proporciona async.callback_url; la invocación síncrona devuelve un error de validación porque la ejecución se pausa hasta que el miembro del workspace configurado envíe una elección.

​
Ejemplo básico

curl 'https://api.fetchhive.com/v1/workflow/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
    "deployment": "YOUR_DEPLOYMENT_NAME",
    "variant": "YOUR_VARIANT_NAME",
    "inputs": {
      "topic": "State of enterprise AI in 2026"
    },
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    }
  }' \
  --compressed
Esto coincide con el fragmento de cURL que se muestra en la interfaz del deployment del flujo de trabajo. La interfaz del deployment muestra actualmente un ejemplo en cURL, y las pestañas de Python y TypeScript aún muestran Coming Soon. Usa metadata para campos de auditoría que quieras ver o filtrar en los registros, como IDs de clientes, nombres de planes, regiones o nombres de experimentos. Las variables de inicio del flujo de trabajo van en inputs. Consulta Metadata de invoke para ver ejemplos y detalles de filtrado de registros.

​
Ejemplo de entrega por callback

curl 'https://api.fetchhive.com/v1/workflow/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
    "deployment": "YOUR_DEPLOYMENT_NAME",
    "variant": "YOUR_VARIANT_NAME",
    "async": {
      "enabled": true,
      "callback_url": "https://example.com/callback"
    },
    "inputs": {
      "topic": "State of enterprise AI in 2026"
    }
  }' \
  --compressed
Consulta Entrega por callback y disparadores de webhook para saber cómo funcionan las respuestas inmediatas y la entrega por callback firmada.

​
Respuesta

​
Respuesta directa

Cuando no habilitas la entrega por callback, la ruta pública espera a que el flujo de trabajo termine y devuelve la salida final. Por ejemplo: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "completed",
  "output": "State of enterprise AI in 2026: enterprises are moving from experimentation to operational systems with stricter evaluation, governance, and tooling requirements."
}

​
Respuesta con entrega por callback

Cuando async.enabled es true, la ruta devuelve respuesta inmediatamente. Por ejemplo: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "running",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}
Con alta concurrencia, la ruta también puede devolver un estado de entrega por callback en cola: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "queued",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}

​
Errores

La ruta devuelve un objeto de error cuando la solicitud es inválida o la ejecución falla. Por ejemplo: 
{
  "error": "Missing required field: deployment or variant"
}
Consulta Manejo de errores para los casos de fallo específicos del flujo de trabajo y Entrega por callback y disparadores de webhook para los errores de validación de callback.

​
Siguientes pasos