Einführung
Die Bird API ist eine einheitliche REST API für alles, was die Plattform leistet. Diese Referenz dokumentiert jeden öffentlichen Endpoint, generiert aus derselben OpenAPI-Spezifikation, die auch die offiziellen SDKs steuert – die Request- und Response-Strukturen hier entsprechen exakt dem, was über die Leitung geht.
Die Seitenleiste der Referenz gruppiert die meistgenutzten Ressourcen nach Produkt: Email, SMS, Voice, Realtime, Verify sowie die Entwicklertools (Webhooks und Documentation, die Dokumentationssuche-API). Weitere öffentliche Endpunkte – darunter Sende-Domains, eingehende E-Mail, Kontakte und Audiences sowie WhatsApp – sind über die Suche und die Direktlinks in den jeweiligen Guides erreichbar. Der Bereich Voice umfasst Anrufe, Leg-Logs, Trunks, Nummern, Anrufer-IDs, Ziele und SIP-Sitzungsanmeldedaten. Voice-Statistiken sind weiterhin über das Dashboard und CLI verfügbar. Workspace-Einstellungen, API-Schlüssel und dedizierte IPs werden im Dashboard verwaltet, nicht über die öffentliche API.
Ressourcenseiten sind aus den Guides heraus direkt verlinkt: Wenn ein Guide einen Endpoint erwähnt, führt der Link hierher zum zugehörigen Referenzeintrag.
Konventionen
Jeder Endpoint folgt denselben Konventionen. Sie werden hier einmal aufgeführt, statt auf jeder Seite wiederholt.
- Basispfad: Alle Endpoints liegen unter /v1 auf einem regionalen Host wie https://us1.platform.bird.com. Siehe Basis-URLs und Regionen.
- Authentifizierung: Requests übermitteln einen API-Schlüssel als Bearer-Token: Authorization: Bearer bk_us1_.... Siehe Authentifizierung.
- JSON, snake_case: Request- und Response-Bodys sind JSON mit snake_case-Feldnamen (created_at, workspace_id), und Requests müssen Content-Type: application/json setzen.
- Zeitstempel: Alle Zeitstempel sind RFC-3339-Strings in UTC, in Feldern mit dem Suffix _at (created_at, delivered_at). Ressourcen-Zeitstempel wie created_at werden vom Server vergeben und sind schreibgeschützt; einige wenige Request-Felder, etwa scheduled_at, sind Zeitstempel, die Sie angeben.
- Typisierte Ressourcen-IDs: Jede ID trägt ein Typ-Präfix: em_ für E-Mail-Nachrichten, dom_ für Sending Domains, whk_ für Webhook-Endpoints, sup_ für Suppressions usw. Das Präfix macht eine ID in Logs selbstbeschreibend und verhindert, dass die ID einer Ressource dort übergeben wird, wo die einer anderen erwartet wird.
- Teilaktualisierungen verwenden PATCH: Eine PATCH-Anfrage ändert nur die Felder, die Sie mitschicken; ausgelassene Felder bleiben unverändert. Einige Subressourcen, die Sie über ihren Namen in der URL ansprechen, werden mit PUT geschrieben, was die Subressource vollständig ersetzt.
- Query-Parameter sind strikt: Ein Request mit einem Query-Parameter, den der Endpoint nicht dokumentiert, wird mit 422 (E01029) abgelehnt, statt ignoriert zu werden. Prüfen Sie die Schreibweise anhand der Parameterliste des Endpoints.
- Fehler: Jede Fehlerantwort trägt dieselbe Struktur, mit einem type für grobe Verzweigung, einem stabilen code, einem menschenlesbaren message und der request_id, die Sie bei Kontakt mit dem Support angeben. Siehe Fehlerantworten.
- Paginierung: Listen-Endpoints verwenden cursorbasierte Paginierung mit einem gemeinsamen Parametersatz. Siehe Paginierung.
- Idempotenz: Mutierende Endpoints akzeptieren einen Idempotency-Key-Header, damit Wiederholungsversuche sicher sind. Siehe Idempotency-Key-Header.
- Deprecations: Ein umbenanntes Feld funktioniert weiterhin unter seinem alten Namen, und eine Response zeigt dies mit einem Deprecation-Header an. Siehe Deprecations.
Empfohlene Clients
Sie können die API mit jedem HTTP-Client aufrufen, aber die offiziellen Clients übernehmen Authentifizierung, Regionswahl, Wiederholungsversuche und Paginierung für Sie:
- Die offiziellen SDKs für TypeScript, Go und Python: typisierte Methoden über die kuratierte öffentliche Oberfläche
- Die Bird CLI: die API von Ihrem Terminal aus, auch geeignet für Skripte und Agents
In Postman ausführen
Die gesamte API ist auch als Postman-Collection verfügbar, konvertiert aus derselben Spezifikation, mit einem Beispiel-Request und -Response für jeden Endpoint. Importieren Sie das Environment für Ihre Region, setzen Sie apiKey auf einen Workspace-API-Schlüssel und senden Sie einen beliebigen Request.
Weiterlesen
- Authentifizierung: wie sich Requests auf Wire-Ebene authentifizieren
- Basis-URLs und Regionen: regionale Hosts und das Regionsmodell
- Paginierung: Cursor, Seitengrößen und Sortierung
- Idempotency-Key-Header: sichere Wiederholungsversuche für mutierende Requests
- Fehlerantworten: die Fehlerantwort-Struktur und der vollständige Fehlerkatalog
- Deprecations: was ein abgelöstes Feld weiterhin tut und wie Sie davon migrieren
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Das Konzept verstehenShould I use a Bird SDK or call the API directly?Dem Lernpfad folgenBuild your first integrationImplementierungsleitfadenSend your first email
Implementierungs-Briefing erhalten