> ## 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 prompt con la API pública usando tu clave de API, nombre del deployment y variante

# Ejecutar con API

Usa el endpoint público de invocación cuando quieras llamar a un prompt desde tu propia aplicación o servicio. Primero crea un deployment de prompt y una variante en el dashboard, luego invoca el deployment con tu clave de API del workspace.

## 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/prompt/invoke`

Antes de llamar a este endpoint, crea o actualiza un deployment de prompt desde el editor de prompts. Consulta [Publicación y versionado](./publishing-and-versioning) para el flujo de la interfaz.

## Solicitud

Usa esta forma de solicitud:

| Campo        | Tipo    | Requerido | Descripción                                                                                                         |
| ------------ | ------- | --------- | ------------------------------------------------------------------------------------------------------------------- |
| `deployment` | string  | Sí        | El nombre del deployment de prompt que creaste para el prompt                                                       |
| `variant`    | string  | Sí        | La variante del deployment de prompt que quieres ejecutar                                                           |
| `inputs`     | object  | No        | Pares clave-valor para cualquier variable de prompt utilizada por el prompt                                         |
| `streaming`  | boolean | No        | Si la respuesta debe transmitirse                                                                                   |
| `metadata`   | object  | No        | Metadata plana definida por quien llama, para auditoría y filtrado de registros. No se usa como entrada del prompt. |

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

Este endpoint no acepta `image_urls` ni `attachments` de documento a nivel superior. Si un prompt desplegado usa una parte de mensaje con URL de imagen, configura
esa URL de imagen en el editor de prompts o vincúlala mediante una variable `inputs` en
el contenido del prompt. Para adjuntos de imagen/documento en tiempo de ejecución, invoca un agente
con [`POST /v1/agent/invoke`](../api-reference/agents/invoke).

## Ejemplo básico

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

Reemplaza `YOUR_API_KEY`, `YOUR_DEPLOYMENT_NAME`, `YOUR_VARIANT_NAME` y el objeto `inputs` con tus valores reales.

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. No pongas variables de prompt ahí; las variables de prompt van en `inputs`. Consulta [Metadata de invoke](../user-tracking/invoke-metadata) para ver ejemplos y detalles de filtrado de registros.

## Respuesta

Si `streaming` es `true`, la API devuelve una transmisión de eventos `data:` en lugar de un solo objeto JSON final. Si el proveedor falla después de que la transmisión se ha abierto, la API envía un evento `error` final antes de cerrar la transmisión.

### Respuesta en streaming

Puedes recibir diferentes tipos de eventos durante la transmisión. Por ejemplo:

Evento de razonamiento o pensamiento:

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

Evento de respuesta:

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

Evento final de uso:

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

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

### Respuesta sin streaming

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

```json theme={null}
{
  "request_id": "req_019d528660dd7e22b15e5b13a1931c50",
  "model": "gpt-5-nano-2025-08-07",
  "duration": 4.641960144042969,
  "reasoning": "**Clarifying summary request**\n\nI need to follow up on the user's request for a 50-word summary since their message was incomplete. I should ask them to clarify the text or topic they'd like summarized. I can suggest options like pasting a passage or specifying a source. I’ll also mention I can summarize up to 50 words or suggest a different length if they prefer. Let’s get that response ready!",
  "response": "I’m missing the text or topic to summarize. Please paste the passage (or name the work) you want summarized, and I’ll provide exactly 50 words. If you prefer a different length, tell me the target word count. I can summarize articles, chapters, speeches, or any provided content.",
  "usage": {
    "prompt_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "completion_tokens": {
      "total_tokens": 187,
      "reasoning_tokens": 64
    },
    "total_tokens": 211
  },
  "stop_reason": "completed"
}
```

## Siguientes pasos

* [Publicación y versionado](./publishing-and-versioning)
* [Ejecutar con el SDK de Python](./run-with-python-sdk) - Invoca un prompt desde Python
* [Ejecutar con el SDK de Node.js](./run-with-nodejs-sdk) - Invoca un prompt desde Node.js
* [Ejecutar con el SDK de Ruby](./run-with-ruby-sdk) - Invoca un prompt desde Ruby
* [Ejecutar con el SDK de PHP](./run-with-php-sdk) - Invoca un prompt desde PHP