REST API · v1

Flowent API-Dokumentation

Steuere Voice-Agenten, führe Pipelines aus und frage deine Wissensbasis programmatisch ab — über eine schlanke REST-API mit Bearer-Authentifizierung, granularen Scopes und vorhersehbaren JSON-Antworten.

API-Schlüssel erstellenhttps://flowentlabs.io/api/v1

Einführung

Die Flowent-API ist eine HTTPS-REST-API. Alle Anfragen und Antworten verwenden JSON (außer dem Streaming-Endpunkt, der Server-Sent-Events liefert). Die Basis-URL ist:

https://flowentlabs.io/api/v1

Sicher per Default

DSGVO-konform, EU-Hosting. Jeder Schlüssel ist auf seine Scopes (und optional IPs) beschränkt.

Agenten & Pipelines

Voice-/KI-Agenten ausführen und visuelle Workflows triggern — alles über einen Endpunkt-Satz.

Asynchron

Lang laufende Aufgaben liefern eine Run-/Execution-ID; den Status pollst du bequem ab.

Quickstart

1Schlüssel erstellen mit den nötigen Scopes (z. B. agents:read).
2Schlüssel sofort kopieren — er wird nur einmal angezeigt.
3Im Authorization-Header als Bearer-Token senden.

cURL — Agenten auflisten

curl https://flowentlabs.io/api/v1/agents \
  -H "Authorization: Bearer flwnt_live_DEIN_SCHLUESSEL"

JavaScript (fetch)

const res = await fetch("https://flowentlabs.io/api/v1/agents", {
  headers: { Authorization: "Bearer flwnt_live_DEIN_SCHLUESSEL" },
});
const { data } = await res.json();
console.log(data);

Python (requests)

import requests

r = requests.get(
    "https://flowentlabs.io/api/v1/agents",
    headers={"Authorization": "Bearer flwnt_live_DEIN_SCHLUESSEL"},
)
print(r.json()["data"])

Authentifizierung

Jede Anfrage braucht einen gültigen API-Schlüssel. Sende ihn als Bearer-Token im Authorization-Header — alternativ wird auch der X-API-Key-Header akzeptiert.

Authorization: Bearer flwnt_live_xxxxxxxxxxxxxxxx
# oder
X-API-Key: flwnt_live_xxxxxxxxxxxxxxxx

Der Schlüssel wird beim Erstellen genau einmal angezeigt — danach speichert Flowent nur den bcrypt-Hash. Bewahre ihn sicher auf (z. B. als Secret in deiner Umgebung), niemals im Client-Code.

Umgebungen & Schlüssel-Format

Jeder Schlüssel gehört zu einer Umgebung. Das Präfix zeigt sie an:

flwnt_live_…	Produktion (Live-Traffic)
flwnt_dev_…	Entwicklung (Sandbox)
flwnt_test_…	Test (Wegwerf)

Pro Schlüssel kannst du zusätzlich ein Rate-Limit, ein Ablaufdatum und eine IP-Allowlist festlegen. Schlüssel lassen sich jederzeit rotieren (neuer Secret, gleiche Konfiguration) oder widerrufen.

Scopes (Berechtigungen)

Scopes legen fest, was ein Schlüssel darf. Ein Endpunkt verlangt mindestens den angegebenen Scope — fehlt er, antwortet die API mit 403 Forbidden. Vergib nach dem Least-Privilege-Prinzip nur das Nötigste.

Scope	Erlaubt
agents:read	Agenten auflisten, Run-Status abfragen
agents:execute	Agenten ausführen (trigger, chat)
agents:write	Agenten erstellen/ändern (reserviert)
knowledge:read · :write · :delete	Wissensbasis verwalten (reserviert)
workflows:read	Pipelines & Ausführungen lesen
workflows:write	Pipelines erstellen, ändern, generieren
workflows:execute	Pipelines ausführen
analytics:read	Nutzungs-Analytics lesen
webhooks:read · :write	Webhooks verwalten
admin:users · :settings · :api_keys	Administration

Rate-Limits

Standardmäßig 1.000 Anfragen pro Stunde pro Schlüssel (pro Schlüssel konfigurierbar). Wird das Limit überschritten, antwortet die API mit 429 Too Many Requests.

Antwort-Header

X-RateLimit-Limit: 1000        # erlaubte Anfragen / Stunde
X-RateLimit-Reset: 2026-06-08T11:00:00Z   # (bei 429) wann das Limit zurücksetzt
X-API-Version: v1

Fehlerformat

Alle Fehler nutzen dieselbe Struktur:

Fehler-Envelope

{
  "error": "Forbidden",
  "message": "Insufficient permissions. Required scopes: agents:read"
}

Status	Typ	Wann
400	Bad request	Ungültiges JSON, falsche ID oder Validierung fehlgeschlagen
401	Unauthorized	Schlüssel fehlt, ungültig oder abgelaufen
403	Forbidden	Fehlende Scopes oder IP nicht in der Allowlist
404	Not found	Ressource existiert nicht
412	Precondition failed	Kein Workspace vorhanden — zuerst einen anlegen
422	Generation failed	KI konnte keine gültige Ausgabe erzeugen
429	Too Many Requests	Rate-Limit überschritten
500	Internal server error	Server-seitiger Fehler

Asynchrone Jobs (Polling)

Lang laufende Operationen (Agent-Trigger, Pipeline-Ausführung) antworten mit 202 Accepted und einer Run-/Execution-ID. Den Status pollst du anschließend ab, bis er nicht mehr pending ist.

Muster

# 1) Job starten
POST /agents/trigger        → { "data": { "runId": "…", "status": "pending" } }

# 2) Status pollen, bis status !== "pending"
GET  /agents/run/{runId}    → { "data": { "status": "success", "output": "…" } }

Streaming (Server-Sent Events)

Der Chat-Endpunkt POST /agents/{id}/chat liefert die Antwort als SSE-Stream (text/event-stream). Jedes Event ist eine JSON-Zeile mit data:-Präfix.

Event-Stream

data: {"chunk":"Du hast "}
data: {"chunk":"7 neue E-Mails."}
data: {"toolCall":{"status":"start","tool":"get_email_summary","displayName":"Get Email Summary"}}
data: {"toolCall":{"status":"complete","tool":"get_email_summary","result":{"success":true}}}
data: {"done":true}

Endpunkte — Agenten

GET/agents agents:read

Listet alle verfügbaren Agenten samt Rolle, Status und Spezialgebieten.

Request

curl https://flowentlabs.io/api/v1/agents \
  -H "Authorization: Bearer flwnt_live_…"

Response

{
  "success": true,
  "data": [
    { "id": "emmie", "name": "Emmie", "role": "Email & Calendar",
      "status": "active", "specialties": ["email","calendar"] }
  ],
  "meta": { "total": 1, "rateLimit": 1000 }
}

POST/agents/trigger agents:execute

Startet eine Agent-Ausführung asynchron und liefert eine runId zum Pollen.

Request

curl -X POST https://flowentlabs.io/api/v1/agents/trigger \
  -H "Authorization: Bearer flwnt_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "emmie", "message": "Fasse meine heutigen E-Mails zusammen" }'

Response

{
  "success": true,
  "data": {
    "runId": "550e8400-e29b-41d4-a716-446655440000",
    "agentId": "emmie",
    "status": "pending"
  }
}

GET/agents/{runId} agents:read

Pollt Status & Ergebnis einer Ausführung. Pfad: /agents/run/{runId}.

Request

curl https://flowentlabs.io/api/v1/agents/run/550e8400-… \
  -H "Authorization: Bearer flwnt_live_…"

Response

{
  "success": true,
  "data": {
    "runId": "550e8400-…",
    "status": "success",
    "output": "Du hast 5 ungelesene E-Mails …",
    "executionTimeMs": 2340,
    "tokensUsed": 450
  }
}

POST/agents/{id}/chat agents:execute

Streamt die Antwort eines Agenten live als SSE (inkl. Tool-Calls). Body: message, optional temperature, maxTokens, useKnowledge.

Request

curl -N -X POST https://flowentlabs.io/api/v1/agents/emmie/chat \
  -H "Authorization: Bearer flwnt_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Was steht heute an?", "temperature": 0.5 }'

Endpunkte — Pipelines

GET/pipelines workflows:read

Listet Pipelines (Paginierung via ?limit=…&offset=…, max. 100).

Request

curl "https://flowentlabs.io/api/v1/pipelines?limit=10&offset=0" \
  -H "Authorization: Bearer flwnt_live_…"

Response

{
  "success": true,
  "data": [
    { "id": "…", "name": "Täglicher Report", "status": "active",
      "executionCount": 5, "updatedAt": "2026-06-08T…" }
  ],
  "meta": { "total": 1, "limit": 10, "offset": 0 }
}

POST/pipelines workflows:write

Erstellt eine neue Pipeline. Body: name (erforderlich), optional description, nodes, edges, viewport.

Request

curl -X POST https://flowentlabs.io/api/v1/pipelines \
  -H "Authorization: Bearer flwnt_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Täglicher Report", "description": "Sendet morgens einen Report" }'

Response

{ "success": true, "data": { "id": "…", "name": "Täglicher Report", "status": "draft", "version": "1.0.0" } }

GET/pipelines/{id} workflows:read

Holt eine Pipeline inklusive der letzten Ausführungen.

PUT/pipelines/{id} workflows:write

Aktualisiert eine Pipeline (Teil-Update). Status auf 'active' erzeugt automatisch ein webhookSecret.

Request

curl -X PUT https://flowentlabs.io/api/v1/pipelines/{id} \
  -H "Authorization: Bearer flwnt_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

DELETE/pipelines/{id} workflows:write

Archiviert (soft-delete) eine Pipeline.

POST/pipelines/{id}/execute workflows:execute

Stellt eine Ausführung in die Queue (BullMQ). Body optional: inputs, variables, priority (0–10), triggerType.

Request

curl -X POST https://flowentlabs.io/api/v1/pipelines/{id}/execute \
  -H "Authorization: Bearer flwnt_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "inputs": { "email": "admin@example.com" }, "priority": 5 }'

Response

{
  "success": true,
  "data": {
    "executionId": "660f9511-…",
    "status": "pending",
    "statusUrl": "/api/v1/pipelines/{id}/execute?executionId=660f9511-…"
  }
}

GET/pipelines/{id}/execute workflows:read

Pollt eine konkrete Ausführung (?executionId=…) oder listet die letzten 50 Ausführungen.

POST/pipelines/generate workflows:write

Generiert eine Pipeline aus einem natürlichsprachigen Prompt (10–5000 Zeichen). save=true speichert sie direkt.

Request

curl -X POST https://flowentlabs.io/api/v1/pipelines/generate \
  -H "Authorization: Bearer flwnt_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Prüfe morgens meine E-Mails und schicke mir eine Zusammenfassung", "save": true }'

Bereit loszulegen?

Erstelle einen API-Schlüssel mit minimalen Rechten und sende deine erste Anfrage in unter einer Minute.

Schlüssel erstellen