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, WhatsApp, Apple Messages, Voice, eSIM, Realtime, Verify, Preferences, Numbers, Lookup, Workspace sowie die Entwicklertools (Webhooks und Documentation, die Dokumentationssuche-API). Sende-Domains, eingehende E-Mail sowie Kontakte und Audiences haben Referenzseiten ohne Seitenleisteneintrag. Starten Sie bei Sende-Domain erstellen, Eingangsadresse erstellen, Kontakt erstellen und Audience erstellen, oder über die zugehörigen Guides: Sende-Domains, E-Mail empfangen, Kontakte und Audiences. 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.

Für Coding-Agents

Verweisen Sie einen Agent auf diese maschinenlesbaren Quellen:

• OpenAPI-Spezifikation: jeder öffentliche Endpoint, jedes Schema und jeder Fehlercode, auch als YAML verfügbar. Die SDKs werden aus derselben Datei generiert.
• API-Index: die API-Guides, jede Operations-Referenz und die öffentlichen Fehler, gruppiert nach Produkt und verlinkt zu ihren Markdown-Seiten.
• Docs-Index: jede veröffentlichte englischsprachige Docs-Seite, gruppiert nach Bereich und Produkt.
• Site-Index: Produkte, Quickstarts und Agent-Tooling auf bird.com.
• MCP server: gehostete Tools unter mcp.bird.com, die nach einer Browser-Anmeldung auf Ihren Workspace zugreifen.
• Bird CLI: die API von einem Terminal aus. CLI for agents beschreibt die JSON-Ausgabe und Exit-Codes.
• Markdown-Seiten: Hängen Sie .md an eine beliebige Docs-URL an, wie in https://bird.com/docs/api.md, oder senden Sie Accept: text/markdown.

Produktübersicht

Jede Tabelle listet die Aufrufe einer Integration in der richtigen Reihenfolge, mit einem Link zur Referenzseite jedes Aufrufs und zu den Guides des Produkts.

Email

SMS

Verify

Weitere Produkte

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 Sende-Domains, whk_ für Webhook-Endpoints, sup_ für Unterdrückungen 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, und lässt ausgelassene Felder 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.

Sie können auch die Collection und ein Environment für us1 oder eu1 direkt herunterladen.

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