> ## 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, Ratenbegrenzung und Idempotenzschlüssel für die Flowella REST API v1 – alles, was Sie vor Ihrem ersten Aufruf brauchen.
Mit der Flowella REST API können Sie WhatsApp-Nachrichten versenden, Kontakte und Opt-Outs verwalten, Vorlagen für Listen- und Massensendungen erstellen und Analysen abrufen - und zwar programmatisch. Auf dieser Seite erfahren Sie alles, was Sie wissen müssen, bevor Sie einen Endpunkt aufrufen.
Die vollständige Endpunktreferenz finden Sie in der Seitenleiste **API-Referenz** (automatisch generiert aus der [OpenAPI-Spezifikation](/api-reference/openapi.json)).
## Basis-URL
```
https://app.flowella.io
```
Alle v1-Endpunkte sind unter `/api/v1`.
## Authentifizierung
Jede Anfrage benötigt einen API-Schlüssel im `Authorization`-Header:
```http theme={null}
Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx
```
Schlüssel sind organisationsbezogen - sie wirken auf eine einzelne Flowella-Organisation und erben die Berechtigungen eines Administrators in dieser Organisation.
Behandeln Sie Schlüssel wie Passwörter. Übertragen Sie sie niemals in die Versionskontrolle, fügen Sie sie niemals in Chats oder gemeinsame Dokumente ein und wechseln Sie sie aus, wenn Teammitglieder die Organisation verlassen. Siehe [Einstellungen → API-Schlüssel](/de/settings/api-keys) für Schritte zur Rotation.
### Einen Schlüssel erstellen
Sie benötigen die Rolle **Owner** oder **Admin**, um API-Schlüssel zu verwalten.
1. Gehen Sie zu **Einstellungen → API-Schlüssel** in der Flowella-App.
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: Übertragen Sie sie nie in die Versionsverwaltung, fügen Sie sie nie im Chat ein und wechseln Sie sie aus, wenn Teamkollegen die Organisation verlassen.
### Überprüfen eines Schlüssels
Drücken Sie den Ping-Endpunkt, um zu bestätigen, dass ein Schlüssel gültig ist:
```bash cURL theme={null}
curl https://app.flowella.io/api/v1/ping \
-H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
```
```js Node.js theme={null}
await fetch("https://app.flowella.io/api/v1/ping", {
headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
});
```
```python Python theme={null}
import os, requests
requests.get(
"https://app.flowella.io/api/v1/ping",
headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
)
```
Ein `200 OK` mit `{ "ok": true, "organizationId": "…" }` bedeutet, dass Sie authentifiziert sind.
## Fehler
Alle Fehler werden in einem einheitlichen Umschlag zurückgegeben:
```json theme={null}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}
```
| HTTP-Status | Wann Sie es sehen werden |
| ----------- | ----------------------------------------------------------------------------------- |
| `400` | Validierung fehlgeschlagen, fehlerhafter Body oder vorgelagerte Meta Ablehnung |
| `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 angeforderte Ressource existiert nicht |
| `429` | Ratenbeschränkung - langsamer werden |
Das Feld `error.code` ist stabil und kann sicher programmatisch eingeschaltet werden. Das `error.message`-Feld ist von Menschen lesbar und kann sich ändern.
## Ratenbegrenzung
API-Schlüssel haben ein Ratenlimit pro Organisation. Wenn Sie das Limit überschreiten, erhalten Sie eine `429` mit dem Code `RATE_LIMITED` und der Nachricht `Too many requests`. Gehen Sie zurück und versuchen Sie es mit exponentieller Verzögerung erneut.
Wenn Sie große Mengen senden, bevorzugen Sie **`POST /api/v1/templates/send`** mit dem Parameter `throttlePerHour` - Flowella setzt die Drosselung serverseitig durch, so dass Sie die Anfragen nicht selbst steuern müssen.
## Paginierung
Listenendpunkte (`/conversations`, `/contacts`, `/templates`) verwenden **Cursor-Paginierung**:
* Übergeben Sie `limit` (1-100, Standardwert 25) und ein optionales `cursor`.
* Die Antwort enthält `items` und, wenn es mehr Ergebnisse gibt, ein `nextCursor`.
* Geben Sie `nextCursor` als Parameter `cursor` zurück, um die nächste Seite zu holen.
* Wenn `nextCursor` fehlt, haben Sie das Ende erreicht.
```bash theme={null}
curl "https://app.flowella.io/api/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`). Wenn die API Datumsangaben akzeptiert, werden sowohl reine Datumsangaben (`2025-01-15`) als auch vollständige ISO 8601-Zeichenfolgen server-seitig erzwungen.
## Telefonnummern
Übergeben Sie Telefonnummern nach Möglichkeit in **E.164**-Form (`+15551234567`). Flowella normalisiert die üblichen Varianten serverseitig, aber E.164 ist am sichersten.
## Kanäle
Viele Endpunkte akzeptieren ein `whatsappChannelId`. Wenn Ihre Organisation nur einen einzigen Kanal hat und Sie diesen weglassen, verwendet Flowella Ihren Standardkanal. Wenn Sie mehrere Kanäle haben, geben Sie die ID explizit an, um zu vermeiden, dass Sie von einem falschen Absender senden.
Das vollständige URL-Muster und die Kanalumschaltung finden Sie unter [Multi-Channel](/de/essentials/multi-channel).
## OpenAPI spec
Die maschinenlesbare Spezifikation finden Sie unter:
```
/api-reference/openapi.json
```
Geben Sie sie in Postman, Insomnia oder den Codegenerator Ihrer Wahl ein.
Bauen Sie eine Integration? Verbinden Sie diese Seite mit [Webhooks](/de/api-reference/webhooks), um auf Ereignisse zu reagieren, anstatt den Status abzufragen.