> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API-Einführung

> Authentifizierung, Basis-URL, Fehlercodes, Paginierung, Ratenlimits und Idempotency-Keys für die Flowella REST API v1 — alles, was Sie vor Ihrem ersten Aufruf benötigen.

Die Flowella REST API ermöglicht es Ihnen, WhatsApp-Nachrichten zu senden, Kontakte und Opt-Outs zu verwalten, Vorlagen aufzulisten und in großen Mengen zu senden sowie Analysen abzurufen — programmatisch. Diese Seite behandelt alles, was Sie wissen müssen, bevor Sie einen Endpunkt aufrufen.

Die vollständige Endpunktreferenz befindet sich in der Seitenleiste **API-Referenz** (automatisch generiert aus der [OpenAPI-Spezifikation](/api-reference/openapi.json)).

## Basis-URL

```
https://api.flowella.io/v1
```

Alle v1-Endpunkte liegen unter dieser kanonischen Basis — zum Beispiel `https://api.flowella.io/v1/messages`.

<Note>
  Die API befand sich zuvor auf dem App-Host unter `https://app.flowella.io/api/v1/...`. Legacy-Anfragen an diesen Pfad werden dauerhaft (`308`) an die kanonische `https://api.flowella.io/v1/...` umgeleitet, wobei Methode und Body erhalten bleiben — sodass bestehende Integrationen weiterhin funktionieren. Aktualisieren Sie Ihre Basis-URL bei Gelegenheit, um den zusätzlichen Hop zu überspringen.
</Note>

## Authentifizierung

Jede Anfrage benötigt einen API-Schlüssel im `Authorization`-Header:

```http theme={null}
Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx
```

Schlüssel sind auf Organisationsebene beschränkt — sie wirken auf eine einzelne Flowella-Organisation und erben die Berechtigungen eines Admins in dieser Organisation.

<Warning>
  Behandeln Sie Schlüssel wie Passwörter. Committen Sie sie niemals in die Versionsverwaltung, fügen Sie sie niemals in Chats oder gemeinsam genutzte Dokumente ein und rotieren Sie sie, wenn Teamkolleg:innen die Organisation verlassen. Siehe [Einstellungen → API-Schlüssel](/de/settings/api-keys) für die Rotationsschritte.
</Warning>

### Einen Schlüssel erstellen

Sie benötigen die Rolle **Owner** oder **Admin**, um API-Schlüssel zu verwalten.

1. Gehen Sie in der Flowella-App zu **Einstellungen → API-Schlüssel**.
2. Klicken Sie auf **Schlüssel erstellen** und geben Sie ihm einen einprägsamen Namen.
3. Kopieren Sie den Schlüssel einmal — er wird nur zum Zeitpunkt der Erstellung angezeigt.

Behandeln Sie Schlüssel wie Passwörter: Committen Sie sie niemals in die Versionsverwaltung, fügen Sie sie niemals in Chats ein und rotieren Sie sie, wenn Teamkolleg:innen die Organisation verlassen.

### Einen Schlüssel überprüfen

Rufen Sie den Ping-Endpunkt auf, um zu bestätigen, dass ein Schlüssel gültig ist:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.flowella.io/v1/ping \
    -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```js Node.js theme={null}
  await fetch("https://api.flowella.io/v1/ping", {
    headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://api.flowella.io/v1/ping",
      headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
  )
  ```
</CodeGroup>

Ein `200 OK` mit `{ "ok": true, "organizationId": "…" }` bedeutet, dass Sie authentifiziert sind.

## Fehler

Alle Fehler kommen in einem einheitlichen Umschlag zurück:

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
```

| HTTP-Status | Wann Sie ihn sehen |
| - | - |
| `400` | Validierung fehlgeschlagen, fehlerhafter Body oder Ablehnung durch Meta |
| `401` | Fehlender oder ungültiger API-Schlüssel |
| `402` | Zahlung erforderlich — Ihr Abonnement deckt die Aktion nicht ab |
| `403` | Verboten — z. B. Senden an einen abgemeldeten Kontakt oder Meta ist nicht verbunden |
| `404` | Der angeforderte Kanal oder die Ressource existiert nicht |
| `429` | Ratenlimit — verlangsamen |

Das Feld `error.code` ist stabil und sicher für programmatische Verzweigungen. Die `error.message` ist für Menschen lesbar und kann sich ändern.

## Ratenlimits

API-Schlüssel sind pro Organisation ratenbegrenzt. Wenn Sie das Limit überschreiten, erhalten Sie ein `429` mit dem Code `RATE_LIMITED` und der Nachricht `Too many requests`. Sofern vorhanden, teilt Ihnen der Response-Header `Retry-After` mit, wie viele Sekunden Sie warten sollen. Backen Sie zurück und wiederholen Sie mit exponentieller Verzögerung.

Wenn Sie große Massensendungen durchführen, bevorzugen Sie **`POST /v1/templates/send`** mit dem Parameter `throttlePerHour` — Flowella erzwingt die Drosselung serverseitig, sodass Sie die Anfragen nicht selbst takten müssen.

## Idempotency-Keys

Massenvorlagen-Sendungen sind asynchron. `POST /v1/templates/send` validiert die Anfrage, stellt sie dauerhaft in die Warteschlange und gibt sofort `202 Accepted` zurück:

```json theme={null}
{
  "id": "v1ts-0123456789abcdef",
  "status": "accepted"
}
```

Flowella liefert den Batch im Hintergrund aus und wiederholt vorübergehende WhatsApp-Fehler automatisch. Empfänger werden einzeln verarbeitet, sodass eine ungültige Nummer den Rest des Batches nicht blockiert. Verfolgen Sie den Zustellfortschritt auf dem Tab **Statistik** der Vorlage in der App.

Da die Zustellung nach der Antwort erfolgt, müssen Wiederholungen sicher sein. Übergeben Sie einen `Idempotency-Key`-Header (bis zu 200 Zeichen), der jeden Batch eindeutig identifiziert:

```bash theme={null}
curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: campaign-2026-08-31-launch" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [{ "phone": "+15551234567" }]
  }'
```

Wiederholungen desselben Schlüssels innerhalb von sieben Tagen geben die ursprüngliche Job-`id` zurück, anstatt eine neue Sendung zu erstellen. Sie können eine Anfrage nach einem Timeout oder Netzwerkfehler sicher wiederholen, ohne jemanden zweimal anzuschreiben.

Wenn Sie den Header weglassen, leitet Flowella einen Schlüssel aus dem Anfragekörper ab. Ein identischer Batch, der zweimal kurz hintereinander gesendet wird, wird daher nicht doppelt gesendet. Ein expliziter Schlüssel ist dennoch sicherer, da jede Änderung am Body (auch das Umordnen von Empfängern) einen neuen abgeleiteten Schlüssel erzeugt.

## Paginierung

Listen-Endpunkte (`/conversations`, `/contacts`, `/templates`) verwenden **Cursor-Paginierung**:

* Übergeben Sie `limit` (1–100, Standard 25) und einen optionalen `cursor`.
* Die Antwort enthält `items` und, wenn weitere Ergebnisse vorhanden sind, einen `nextCursor`.
* Übergeben Sie `nextCursor` als `cursor`-Parameter zurück, um die nächste Seite abzurufen.
* Wenn `nextCursor` fehlt, haben Sie das Ende erreicht.

```bash theme={null}
curl "https://api.flowella.io/v1/conversations?limit=50" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
```

## Datum und Uhrzeit

Alle Zeitstempel sind ISO 8601-Strings in UTC (zum Beispiel `2025-01-15T14:30:00.000Z`). Wo die API Daten akzeptiert, werden sowohl nur-Datum (`2025-01-15`) als auch vollständiges ISO 8601 serverseitig zwangskonvertiert.

## Telefonnummern

Übergeben Sie Telefonnummern nach Möglichkeit in **E.164**-Form (`+15551234567`). Flowella normalisiert gängige Varianten serverseitig, aber E.164 ist am sichersten.

## Kanäle

Viele Endpunkte akzeptieren eine `whatsappChannelId`. Wenn Ihre Organisation einen einzelnen Kanal hat und Sie sie weglassen, verwendet Flowella Ihren Standardkanal. Wenn Sie mehrere Kanäle haben, übergeben Sie die ID explizit, um zu vermeiden, dass Sie vom falschen Absender senden.

Für das vollständige URL-Muster und das Wechseln von Kanälen siehe [Multi-Channel](/de/essentials/multi-channel).

## OpenAPI-Spezifikation

Die maschinenlesbare Spezifikation befindet sich unter:

```
/api-reference/openapi.json
```

Legen Sie sie in Postman, Insomnia oder Ihren bevorzugten Code-Generator ein.

<Tip>
  Bauen Sie eine Integration? Kombinieren Sie diese Seite mit [Webhooks](/de/api-reference/webhooks), um auf Ereignisse zu reagieren, anstatt den Status abzufragen.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.