> ## 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 prompt con la API pública de Fetch Hive usando un nombre de despliegue y una variante

# Invocar prompt

`POST /v1/prompt/invoke`

Ejecuta un despliegue de prompt 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 **Prompts**, luego **Deployments**, abre la variante del despliegue que deseas ejecutar y haz clic en **Code Snippet** para ver esta forma de la solicitud en Fetch Hive.

| Campo        | Tipo    | Requerido | Descripción                                                                                                                |
| ------------ | ------- | --------- | -------------------------------------------------------------------------------------------------------------------------- |
| `deployment` | string  | Sí        | El nombre del despliegue del prompt                                                                                        |
| `variant`    | string  | Sí        | El nombre de la variante del despliegue                                                                                    |
| `inputs`     | object  | No        | Pares clave-valor para las variables del prompt                                                                            |
| `streaming`  | boolean | No        | Transmite eventos de respuesta en lugar de esperar una única respuesta JSON final                                          |
| `metadata`   | object  | No        | Metadatos planos definidos por el llamador para auditoría y filtrado de registros. Esto no se usa como entrada del prompt. |

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

`POST /v1/prompt/invoke` no acepta `image_urls` ni `attachments` de documentos a nivel
superior. Si un prompt desplegado usa una parte de mensaje con URL de imagen, configura
esa URL de imagen en el editor del prompt o enlázala mediante una variable de `inputs` en
el contenido del prompt. Para adjuntos de imagen/documento en runtime, usa
[`POST /v1/agent/invoke`](../agents/invoke).

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

## Respuesta

Si `streaming` es `true`, Fetch Hive devuelve un flujo de eventos. Si el proveedor falla después de que se haya abierto el flujo, Fetch Hive envía un evento `error` final antes de cerrar el flujo.

Evento de razonamiento de ejemplo:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "reasoning",
  "model": "gpt-5-nano",
  "response": " seems"
}
```

Evento de respuesta de ejemplo:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "response",
  "model": "gpt-5-nano",
  "response": " too"
}
```

Evento final de uso de ejemplo:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "usage",
  "usage": {
    "duration": 4.79230260848999,
    "prompt_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "completion_tokens": {
      "total_tokens": 170,
      "reasoning_tokens": 64
    },
    "total_tokens": 194
  },
  "stop_reason": "completed"
}
```

Evento de error de ejemplo:

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "error",
  "error": "cohere provider stream error: HTTP 400: invalid request",
  "message": "cohere provider stream error: HTTP 400: invalid request",
  "provider": "cohere",
  "error_type": "provider_stream_error",
  "status_code": 502
}
```

Si `streaming` es `false`, Fetch Hive devuelve una sola respuesta JSON. Los fallos de ejecución del proveedor devuelven `502 Bad Gateway` con un mensaje `error`.

```json theme={null}
{
  "request_id": "req_019d528660dd7e22b15e5b13a1931c50",
  "model": "gpt-5-nano-2025-08-07",
  "duration": 4.641960144042969,
  "reasoning": "The request asks for a short summary.",
  "response": "Fetch Hive helps teams ship AI products faster.",
  "usage": {
    "prompt_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "completion_tokens": {
      "total_tokens": 187,
      "reasoning_tokens": 64
    },
    "total_tokens": 211
  },
  "stop_reason": "completed"
}
```

## Ejemplo

```bash theme={null}
curl 'https://api.fetchhive.com/v1/prompt/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": {
      "text": "Fetch Hive helps teams ship AI products faster."
    },
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    },
    "streaming": true
  }' \
  --compressed
```

## Disparador webhook

`POST /v1/prompt/webhooks/{prompt_endpoint_id}/variants/{variant_id}`

Usa un disparador webhook de prompt cuando un servicio externo deba iniciar una variante de prompt desplegada sin una clave de API del espacio de trabajo. La solicitud debe incluir el secreto webhook del endpoint del prompt en `X-Fetch-Hive-Webhook-Secret`. Si una herramienta de terceros no puede establecer encabezados personalizados, usa `?secret=YOUR_WEBHOOK_SECRET` como alternativa.

Los disparadores webhook de prompt siempre usan entrega por callback. Incluye `async.callback_url`; Fetch Hive devuelve `202` con `request_id` y `run_status: "running"`, y luego entrega `prompt.completed` o `prompt.failed` a la URL de callback.

```bash theme={null}
curl 'https://api.fetchhive.com/v1/prompt/webhooks/YOUR_PROMPT_ENDPOINT_ID/variants/YOUR_VARIANT_ID' \
  -H 'X-Fetch-Hive-Webhook-Secret: YOUR_WEBHOOK_SECRET' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "inputs": {
      "text": "Fetch Hive helps teams ship AI products faster."
    },
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    },
    "user": "external-user-1",
    "async": {
      "callback_url": "https://example.com/callback"
    }
  }'
```

`inputs` debe ser un objeto. Cada variable declarada en la versión del prompt desplegado seleccionada debe estar presente, pero los valores pueden ser cadenas vacías o `null` cuando deseas intencionalmente un render en blanco. Se permiten claves de entrada adicionales. `metadata` sigue la misma regla plana de solo escalares que las invocaciones normales de prompt y aparece en el filtrado de registros.

Fetch Hive firma el callback saliente con el mismo secreto webhook usado para la autenticación del disparador entrante.
El `data` del callback contiene `response` en `prompt.completed` y `error` en `prompt.failed`; usa el `event_type` y el `request_id` de nivel superior para el estado terminal y la correlación.

## Relacionado

* Consulta [Autenticación](./authentication) para configurar la clave de API
* Consulta [Prompts](../prompts/overview) para el editor de prompts y el contexto de despliegue
* Consulta [Ejecutar con API](../prompts/run-with-api) para una guía centrada en el prompt