---
title: API Trigger
description: Start a workflow from an authenticated HTTP request
---

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

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

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

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

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

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

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

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

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

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

| Reference | Description |
|-----------|-------------|
| `<api.field>` | Field defined in the Input Format |
| `<api.input>` | Entire structured request body |

### File Upload Format

The API accepts files in two formats:

**1. Base64-encoded files** (recommended for SDKs):
```json
{
  "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**:
```json
{
  "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:

| Property | Description | Type |
|----------|-------------|------|
| `<api.fieldName[0].url>` | Signed download URL | string |
| `<api.fieldName[0].name>` | Original filename | string |
| `<api.fieldName[0].size>` | File size in bytes | number |
| `<api.fieldName[0].type>` | MIME type | string |
| `<api.fieldName[0].uploadedAt>` | Upload timestamp (ISO 8601) | string |
| `<api.fieldName[0].expiresAt>` | URL expiry timestamp (ISO 8601) | string |

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.

<Callout type="warning">
A workflow can contain only one API Trigger. Publish a new deployment after changes so the endpoint stays up to date.
</Callout>
