API-Trigger

Ü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

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

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

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

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

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:

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

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

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

Datei-Upload-Format

Die API akzeptiert Dateien in zwei Formaten:

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

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

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

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.