---
title: Disparador de API
description: Inicia un flujo de trabajo desde una solicitud HTTP autenticada
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Image } from '@/components/ui/image'

## Descripción general

El disparador de API expone tu flujo de trabajo como un punto de conexión HTTP seguro. Envía datos JSON al punto de conexión y tu flujo de trabajo los procesa inmediatamente. Las llamadas a la API siempre se ejecutan contra tu última implementación.

## Configurar formato de entrada

<div className='flex justify-center my-6'>
  <Image
    src='/static/triggers/api-trigger-light.png'
    alt='Formato de entrada del disparador de API'
    width={400}
    height={250}
    className='rounded-xl border border-border shadow-sm'
  />
</div>

Añade un campo de **Formato de entrada** para cada parámetro. Las claves de salida en tiempo de ejecución reflejan el esquema y también están disponibles bajo `<api.input>`.

Las ejecuciones manuales en el editor utilizan la columna `value` para que puedas realizar pruebas sin enviar una solicitud. Durante la ejecución, el resolutor completa tanto `<api.userId>` como `<api.input.userId>`.

## Ejemplo de solicitud

```bash
curl -X POST \
  https://sim.ai/api/workflows/WORKFLOW_ID/execute \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_KEY' \
  -d '{"userId":"demo-user","maxTokens":1024}'
```

Las respuestas exitosas devuelven el resultado de ejecución serializado del Ejecutor. Los errores muestran fallos de validación, autenticación o flujo de trabajo.

## Respuestas en streaming

Habilita el streaming en tiempo real para recibir la salida del flujo de trabajo a medida que se genera, carácter por carácter. Esto es útil para mostrar las respuestas de IA progresivamente a los usuarios.

### Parámetros de solicitud

Añade estos parámetros para habilitar el streaming:

- `stream` - Establece a `true` para habilitar el streaming de eventos enviados por el servidor (SSE)
- `selectedOutputs` - Array de salidas de bloques para transmitir (p. ej., `["agent1.content"]`)

### Formato de salida de bloque

Usa el formato `blockName.attribute` para especificar qué salidas de bloques transmitir:
- Formato: `"blockName.attribute"` (p. ej., si quieres transmitir el contenido del bloque Agente 1, usarías `"agent1.content"`)
- Los nombres de los bloques no distinguen entre mayúsculas y minúsculas y se ignoran los espacios

### Ejemplo de solicitud

```bash
curl -X POST \
  https://sim.ai/api/workflows/WORKFLOW_ID/execute \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_KEY' \
  -d '{
    "message": "Count to five",
    "stream": true,
    "selectedOutputs": ["agent1.content"]
  }'
```

### Formato de respuesta

Las respuestas en streaming utilizan el formato de eventos enviados por el servidor (SSE):

```
data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":"One"}

data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":", two"}

data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":", three"}

data: {"event":"done","success":true,"output":{},"metadata":{"duration":610}}

data: [DONE]
```

Cada evento incluye:
- **Fragmentos de streaming**: `{"blockId": "...", "chunk": "text"}` - Texto en tiempo real a medida que se genera
- **Evento final**: `{"event": "done", ...}` - Metadatos de ejecución y resultados completos
- **Terminador**: `[DONE]` - Señala el fin del stream

### Streaming de múltiples bloques

Cuando `selectedOutputs` incluye múltiples bloques, cada fragmento indica qué bloque lo produjo:

```bash
curl -X POST \
  https://sim.ai/api/workflows/WORKFLOW_ID/execute \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_KEY' \
  -d '{
    "message": "Process this request",
    "stream": true,
    "selectedOutputs": ["agent1.content", "agent2.content"]
  }'
```

El campo `blockId` en cada fragmento te permite dirigir la salida al elemento de UI correcto:

```
data: {"blockId":"agent1-uuid","chunk":"Processing..."}

data: {"blockId":"agent2-uuid","chunk":"Analyzing..."}

data: {"blockId":"agent1-uuid","chunk":" complete"}
```

## Referencia de salida

| Referencia | Descripción |
|-----------|-------------|
| `<api.field>` | Campo definido en el formato de entrada |
| `<api.input>` | Cuerpo de solicitud estructurado completo |

Si no se define un formato de entrada, el ejecutor expone el JSON sin procesar solo en `<api.input>`.

<Callout type="warning">
Un flujo de trabajo puede contener solo un disparador de API. Publica una nueva implementación después de los cambios para que el endpoint se mantenga actualizado.
</Callout>

### Formato de carga de archivos

La API acepta archivos en dos formatos:

**1. Archivos codificados en Base64** (recomendado para SDKs):

```json
{
  "documents": [{
    "type": "file",
    "data": "data:application/pdf;base64,JVBERi0xLjQK...",
    "name": "document.pdf",
    "mime": "application/pdf"
  }]
}
```

- Tamaño máximo de archivo: 20MB por archivo
- Los archivos se suben al almacenamiento en la nube y se convierten en objetos UserFile con todas las propiedades

**2. Referencias directas de URL**:

```json
{
  "documents": [{
    "type": "url",
    "data": "https://example.com/document.pdf",
    "name": "document.pdf",
    "mime": "application/pdf"
  }]
}
```

- El archivo no se sube, la URL se pasa directamente
- Útil para referenciar archivos existentes

### Propiedades de archivos

Para archivos, accede a todas las propiedades:

| Propiedad | Descripción | Tipo |
|----------|-------------|------|
| `<api.fieldName[0].url>` | URL de descarga firmada | string |
| `<api.fieldName[0].name>` | Nombre original del archivo | string |
| `<api.fieldName[0].size>` | Tamaño del archivo en bytes | number |
| `<api.fieldName[0].type>` | Tipo MIME | string |
| `<api.fieldName[0].uploadedAt>` | Marca de tiempo de subida (ISO 8601) | string |
| `<api.fieldName[0].expiresAt>` | Marca de tiempo de caducidad de URL (ISO 8601) | string |

Para archivos referenciados por URL, las mismas propiedades están disponibles excepto `uploadedAt` y `expiresAt` ya que el archivo no se sube a nuestro almacenamiento.

Si no se define un formato de entrada, el ejecutor expone solo el JSON sin procesar en `<api.input>`.

<Callout type="warning">
Un flujo de trabajo puede contener solo un disparador de API. Publica una nueva implementación después de los cambios para que el punto de conexión se mantenga actualizado.
</Callout>
