Disparador de API

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

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

curl -X POST \
  https://www.ekinox.app/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

curl -X POST \
  https://www.ekinox.app/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:

curl -X POST \
  https://www.ekinox.app/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

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

Formato de carga de archivos

La API acepta archivos en dos formatos:

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

{
  "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:

{
  "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:

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