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:

Campo	Tipo	Requerido	Descripción
`deployment`	string	Sí	La clave del deployment del flujo de trabajo
`variant`	string	Sí	La variante de deployment que quieres ejecutar
`inputs`	object	No	Pares clave-valor para las variables definidas en el paso Start del flujo de trabajo
`async`	object	No	Ajustes de entrega por callback. Consulta Entrega por callback y disparadores de webhook
`metadata`	object	No	Metadata 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:

Campo	Tipo	Requerido	Descripción
`async.enabled`	boolean	Sí	Configúralo en `true` para devolver respuesta inmediatamente y entregar el resultado más tarde mediante callback firmado
`async.callback_url`	string	Sí cuando la entrega por callback está habilitada	La 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.

Primeros pasos

Live Chat

Prompts

Flujos de trabajo

Hive Agents

Agentes

Bases de conocimientos

Experimentos

Tu espacio de trabajo

Monitoreo

Seguimiento de usuarios

Recursos

Ejecutar con API

Ejecutar con API

Autenticación

Endpoint

Solicitud

Ejemplo básico

Ejemplo de entrega por callback

Respuesta

Respuesta directa

Respuesta con entrega por callback

Errores

Siguientes pasos

​Ejecutar con API

​Autenticación

​Endpoint

​Solicitud

​Ejemplo básico

​Ejemplo de entrega por callback

​Respuesta

​Respuesta directa

​Respuesta con entrega por callback

​Errores

​Siguientes pasos

Ejecutar con API

Autenticación

Endpoint

Solicitud

Ejemplo básico

Ejemplo de entrega por callback

Respuesta

Respuesta directa

Respuesta con entrega por callback

Errores

Siguientes pasos