> ## 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.

# Ejecutar con API

> Invoca un deployment de flujo de trabajo con la API pública usando tu clave de API, nombre del deployment, variante y entradas de inicio

# 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](./async-and-webhooks).

## Autenticación

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

Consulta [API Keys](../workspace/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](./publishing-and-versioning) 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](./async-and-webhooks)              |
| `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

```bash theme={null}
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](../user-tracking/invoke-metadata) para ver ejemplos y detalles de filtrado de registros.

## Ejemplo de entrega por callback

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

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

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

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

```json theme={null}
{
  "error": "Missing required field: deployment or variant"
}
```

Consulta [Manejo de errores](./error-handling) para los casos de fallo específicos del flujo de trabajo y [Entrega por callback y disparadores de webhook](./async-and-webhooks) para los errores de validación de callback.

## Siguientes pasos

* [Entrega por callback y disparadores de webhook](./async-and-webhooks)
* [Manejo de errores](./error-handling)
* [Ejecutar con el SDK de Python](./run-with-python-sdk)
* [Ejecutar con el SDK de Node.js](./run-with-nodejs-sdk)
* [Ejecutar con el SDK de Ruby](./run-with-ruby-sdk)
* [Ejecutar con el SDK de PHP](./run-with-php-sdk)