---
title: API-Trigger
description: Starten Sie einen Workflow über eine authentifizierte HTTP-Anfrage
---

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

## Übersicht

Der API-Trigger stellt Ihren Workflow als sicheren HTTP-Endpunkt bereit. Senden Sie JSON-Daten an den Endpunkt und Ihr Workflow verarbeitet diese sofort. API-Aufrufe werden immer gegen Ihre neueste Bereitstellung ausgeführt.

## Eingabeformat konfigurieren

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

Fügen Sie für jeden Parameter ein Feld **Eingabeformat** hinzu. Die Ausgabeschlüssel zur Laufzeit spiegeln das Schema wider und sind auch unter `<api.input>` verfügbar.

Manuelle Ausführungen im Editor verwenden die Spalte `value`, damit Sie testen können, ohne eine Anfrage zu senden. Während der Ausführung füllt der Resolver sowohl `<api.userId>` als auch `<api.input.userId>` aus.

## Anfrage-Beispiel

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

Erfolgreiche Antworten geben das serialisierte Ausführungsergebnis vom Executor zurück. Fehler zeigen Validierungs-, Authentifizierungs- oder Workflow-Fehler an.

## Streaming-Antworten

Aktivieren Sie Echtzeit-Streaming, um Workflow-Ausgaben zu erhalten, während sie zeichen-für-zeichen generiert werden. Dies ist nützlich, um KI-Antworten progressiv für Benutzer anzuzeigen.

### Anfrageparameter

Fügen Sie diese Parameter hinzu, um Streaming zu aktivieren:

- `stream` - Auf `true` setzen, um Server-Sent Events (SSE) Streaming zu aktivieren
- `selectedOutputs` - Array von Block-Ausgaben zum Streamen (z.B. `["agent1.content"]`)

### Block-Ausgabeformat

Verwenden Sie das `blockName.attribute` Format, um anzugeben, welche Block-Ausgaben gestreamt werden sollen:
- Format: `"blockName.attribute"` (z.B. Wenn Sie den Inhalt des Agent 1-Blocks streamen möchten, würden Sie `"agent1.content"` verwenden)
- Blocknamen sind nicht case-sensitive und Leerzeichen werden ignoriert

### Beispielanfrage

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

### Antwortformat

Streaming-Antworten verwenden das 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]
```

Jedes Ereignis enthält:
- **Streaming-Chunks**: `{"blockId": "...", "chunk": "text"}` - Echtzeit-Text während er generiert wird
- **Abschlussereignis**: `{"event": "done", ...}` - Ausführungsmetadaten und vollständige Ergebnisse
- **Terminator**: `[DONE]` - Signalisiert das Ende des Streams

### Streaming mehrerer Blöcke

Wenn `selectedOutputs` mehrere Blöcke enthält, zeigt jeder Chunk an, welcher Block ihn erzeugt hat:

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

Das Feld `blockId` in jedem Chunk ermöglicht es Ihnen, die Ausgabe zum richtigen UI-Element zu leiten:

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

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

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

## Ausgabereferenz

| Referenz | Beschreibung |
|-----------|-------------|
| `<api.field>` | Im Eingabeformat definiertes Feld |
| `<api.input>` | Gesamter strukturierter Anfragekörper |

Wenn kein Eingabeformat definiert ist, stellt der Executor das rohe JSON nur unter `<api.input>` zur Verfügung.

<Callout type="warning">
Ein Workflow kann nur einen API-Trigger enthalten. Veröffentlichen Sie nach Änderungen eine neue Bereitstellung, damit der Endpunkt aktuell bleibt.
</Callout>

### Datei-Upload-Format

Die API akzeptiert Dateien in zwei Formaten:

**1. Base64-kodierte Dateien** (empfohlen für SDKs):

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

- Maximale Dateigröße: 20MB pro Datei
- Dateien werden in den Cloud-Speicher hochgeladen und in UserFile-Objekte mit allen Eigenschaften umgewandelt

**2. Direkte URL-Referenzen**:

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

- Die Datei wird nicht hochgeladen, die URL wird direkt weitergegeben
- Nützlich für die Referenzierung bestehender Dateien

### Dateieigenschaften

Für Dateien können alle Eigenschaften abgerufen werden:

| Eigenschaft | Beschreibung | Typ |
|----------|-------------|------|
| `<api.fieldName[0].url>` | Signierte Download-URL | string |
| `<api.fieldName[0].name>` | Ursprünglicher Dateiname | string |
| `<api.fieldName[0].size>` | Dateigröße in Bytes | number |
| `<api.fieldName[0].type>` | MIME-Typ | string |
| `<api.fieldName[0].uploadedAt>` | Upload-Zeitstempel (ISO 8601) | string |
| `<api.fieldName[0].expiresAt>` | URL-Ablaufzeitstempel (ISO 8601) | string |

Für URL-referenzierte Dateien sind dieselben Eigenschaften verfügbar, außer `uploadedAt` und `expiresAt`, da die Datei nicht in unseren Speicher hochgeladen wird.

Wenn kein Eingabeformat definiert ist, stellt der Executor das rohe JSON nur unter `<api.input>` zur Verfügung.

<Callout type="warning">
Ein Workflow kann nur einen API-Trigger enthalten. Veröffentlichen Sie nach Änderungen eine neue Bereitstellung, damit der Endpunkt aktuell bleibt.
</Callout>
