API Trigger

Overview

The API trigger exposes your workflow as a secure HTTP endpoint. Send JSON data to the endpoint and your workflow processes it immediately. API calls always execute against your latest deployment.

Configure Input Format

Add an Input Format field for each parameter. Supported types:

• string - Text values
• number - Numeric values
• boolean - True/false values
• json - JSON objects
• files - File uploads (access via <api.fieldName[0].url>, <api.fieldName[0].name>, etc.)

Runtime output keys mirror the schema and are available under <api.input>.

Manual runs in the editor use the value column so you can test without sending a request. During execution the resolver populates both <api.fieldName> and <api.input.fieldName>.

Request Example

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

Successful responses return the serialized execution result from the Executor. Errors surface validation, auth, or workflow failures.

Streaming Responses

Enable real-time streaming to receive workflow output as it's generated, character-by-character. This is useful for displaying AI responses progressively to users.

Request Parameters

Add these parameters to enable streaming:

• stream - Set to true to enable Server-Sent Events (SSE) streaming
• selectedOutputs - Array of block outputs to stream (e.g., ["agent1.content"])

Block Output Format

Use the blockName.attribute format to specify which block outputs to stream:

• Format: "blockName.attribute" (e.g., If you want to stream the content of the Agent 1 block, you would use "agent1.content")
• Block names are case-insensitive and spaces are ignored

Example Request

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

Response Format

Streaming responses use Server-Sent Events (SSE) format:

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]

Each event includes:

• Streaming chunks: {"blockId": "...", "chunk": "text"} - Real-time text as it's generated
• Final event: {"event": "done", ...} - Execution metadata and complete results
• Terminator: [DONE] - Signals end of stream

Multiple Block Streaming

When selectedOutputs includes multiple blocks, each chunk indicates which block produced it:

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

The blockId field in each chunk lets you route output to the correct UI element:

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

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

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

Output Reference

File Upload Format

The API accepts files in two formats:

1. Base64-encoded files (recommended for SDKs):

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

• Maximum file size: 20MB per file
• Files are uploaded to cloud storage and converted to UserFile objects with all properties

2. Direct URL references:

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

• File is not uploaded, URL is passed through directly
• Useful for referencing existing files

File Properties

For files, access all properties:

For URL-referenced files, the same properties are available except uploadedAt and expiresAt since the file is not uploaded to our storage.

If no Input Format is defined, the executor exposes the raw JSON at <api.input> only.