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

> Ejecuta un despliegue de flujo de trabajo con la API pública de Fetch Hive usando un nombre de despliegue, una variante y entradas de inicio

# Invocar flujo de trabajo

`POST /v1/workflow/invoke`

Ejecuta un despliegue de flujo de trabajo desde tu propia app o servicio.

## Autenticación

Envía tu clave de API del espacio de trabajo en el encabezado `Authorization`.

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

## Cuerpo de la solicitud

Abre **Workflows**, luego **Deployments**, abre la variante del despliegue que deseas ejecutar y haz clic en **Code Snippet** para copiar la forma actual de la solicitud desde Fetch Hive.

| Campo        | Tipo   | Requerido | Descripción                                                                                                                          |
| ------------ | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `deployment` | string | Sí        | El nombre del despliegue del flujo de trabajo                                                                                        |
| `variant`    | string | Sí        | El nombre de la variante del despliegue                                                                                              |
| `inputs`     | object | No        | Pares clave-valor para las variables definidas en el paso **Start**                                                                  |
| `async`      | object | No        | Ajustes de entrega por callback                                                                                                      |
| `metadata`   | object | No        | Metadatos planos definidos por el llamador para auditoría y filtrado de registros. Esto no se usa como entrada del flujo de trabajo. |

Los valores de `inputs` se validan contra las definiciones de entrada del paso **Start** del flujo de trabajo antes de iniciar la ejecución. Las entradas de inicio de tipo arreglo deben ser arreglos JSON nativos, no cadenas JSON.

`metadata` debe ser un objeto plano. Las claves deben ser cadenas no vacías y los valores deben ser cadenas, números, booleanos o `null`. Los arreglos y objetos anidados se rechazan antes de iniciar la ejecución.

Válido:

```json theme={null}
{
  "metadata": {
    "customer_id": "cus_123",
    "plan": "enterprise",
    "trial": false,
    "invoice_count": 12,
    "region": null
  }
}
```

Inválido:

```json theme={null}
{
  "metadata": {
    "customer": {
      "id": "cus_123"
    },
    "tags": ["enterprise"]
  }
}
```

Si incluyes `async`, usa estos campos anidados:

| Campo                | Tipo    | Requerido                                         | Descripción                                                               |
| -------------------- | ------- | ------------------------------------------------- | ------------------------------------------------------------------------- |
| `async.enabled`      | boolean | Sí                                                | Establece en `true` para devolver inmediatamente                          |
| `async.callback_url` | string  | Sí cuando la entrega por callback está habilitada | La URL de callback que Fetch Hive debe llamar cuando termine la ejecución |

Si activas **Callback delivery** en el diálogo de fragmento de código, Fetch Hive también muestra un **Signing secret** para la verificación del callback.

{/* Add screenshot: Signing secret section in the workflow code snippet modal */}

## Respuesta

Cuando la entrega por callback está desactivada, Fetch Hive espera a que termine el flujo de trabajo y devuelve la salida en una sola respuesta.

```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."
}
```

`output` depende de la forma según el tipo de resultado del flujo de trabajo. Para salidas finales de generación de imágenes, `output` es un objeto con `settings` y `assets`:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "completed",
  "output": {
    "settings": {
      "model": "grok-imagine-image-quality",
      "provider": "xai",
      "image_count": 1
    },
    "assets": [
      {
        "id": "asset_1",
        "file_url": "https://uploads.fetchhive.com/...png",
        "file_name": "step_3_123456789_1.png",
        "file_size": 505042,
        "file_type": "image/png"
      }
    ]
  }
}
```

Cuando `async.enabled` es `true`, Fetch Hive devuelve inmediatamente.

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "running",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}
```

Con alta concurrencia, Fetch Hive también puede devolver un estado de entrega por callback encolada.

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "queued",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}
```

## Ejemplo

### Solicitud directa

```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
```

### Solicitud con 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
```

## Relacionado

* Consulta [Autenticación](./authentication) para configurar la clave de API
* Consulta [Entrega por callback y disparadores webhook](../workflows/async-and-webhooks) para la entrega por callback y la verificación de firmas
* Consulta [Ejecutar con API](../workflows/run-with-api) para una guía centrada en flujos de trabajo