--- title: "Einführung" description: "Orientierung für die Bird-API-Referenz: wie sie aufgebaut ist, welche Konventionen jeder Endpoint einhält und wo Sie anfangen." canonical: "https://bird.com/de-de/dokumentation/api" --- # 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](/docs/api/reference/create-domain), [Eingangsadresse erstellen](/docs/api/reference/create-inbound-address), [Kontakt erstellen](/docs/api/reference/create-contact) und [Audience erstellen](/docs/api/reference/create-audience), oder über die zugehörigen Guides: [Sende-Domains](/docs/guides/email/sending-domains), [E-Mail empfangen](/docs/guides/email/receiving-email), [Kontakte](/docs/guides/email/contacts) und [Audiences](/docs/guides/email/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](/docs/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](/openapi.json): jeder öffentliche Endpoint, jedes Schema und jeder Fehlercode, auch als [YAML](/openapi.yaml) verfügbar. Die SDKs werden aus derselben Datei generiert. - [API-Index](/api/llms.txt): die API-Guides, jede Operations-Referenz und die öffentlichen Fehler, gruppiert nach Produkt und verlinkt zu ihren Markdown-Seiten. - [Docs-Index](/docs/llms.txt): jede veröffentlichte englischsprachige Docs-Seite, gruppiert nach Bereich und Produkt. - [Site-Index](/llms.txt): Produkte, Quickstarts und Agent-Tooling auf bird.com. - [MCP server](/docs/ai/mcp-server): gehostete Tools unter `mcp.bird.com`, die nach einer Browser-Anmeldung auf Ihren Workspace zugreifen. - [Bird CLI](/docs/cli): die API von einem Terminal aus. [CLI for agents](/docs/ai/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 | Schritt | Aufruf | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Einrichtung | [`POST /v1/email/domains`](/docs/api/reference/create-domain), dann [`POST /v1/email/domains/{domain_id}/verify`](/docs/api/reference/verify-domain), nachdem Sie die DNS-Einträge der Domain veröffentlicht haben. Ein Testversand über die gemeinsame Onboarding-Domain von Bird benötigt beides nicht. | | Senden | [`POST /v1/email/messages`](/docs/api/reference/create-email-message) | | Ergebnis | [`GET /v1/email/messages/{message_id}`](/docs/api/reference/get-email-message) oder die [E-Mail-Events](/docs/guides/email/events), die an Ihren Webhook-Endpoint gesendet werden | | Guide | [E-Mail-Übersicht](/docs/guides/email/overview) und [Ihre erste E-Mail senden](/docs/get-started/send-your-first-email) | ### SMS | Schritt | Aufruf | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Einrichten | Aktivieren Sie das Zielland unter [**SMS** > **Destinations**](https://bird.com/dashboard/w/sms/destinations), mit `bird sms destinations update` im CLI oder mit dem `sms_destinations_update`-MCP-Tool. Die öffentliche API hat keine Ziel- oder Absenderoperationen. | | Senden | [`POST /v1/sms/messages`](/docs/api/reference/create-sms-message). Ein eingebautes Template wählt seinen eigenen Absender. Freitext benötigt einen [Absender](/docs/guides/sms/senders), den Ihr Workspace nutzen kann. | | Ergebnis | [`GET /v1/sms/messages/{message_id}`](/docs/api/reference/get-sms-message), oder die `sms.*`-[SMS-Events](/docs/guides/sms/events), die an Ihren Webhook-Endpoint gesendet werden | | Guide | [SMS-Übersicht](/docs/guides/sms/overview) und [Erste SMS senden](/docs/get-started/send-your-first-sms) | ### Verify | Schritt | Aufruf | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Einrichten | Nicht nötig. Die gemeinsamen [Absender](/docs/guides/verify/senders) von Bird stellen den Code ohne Absenderregistrierung zu. | | Senden | [`POST /v1/verify/verifications`](/docs/api/reference/create-verification) | | Ergebnis | [`POST /v1/verify/verifications/check`](/docs/api/reference/create-verification-check) prüft den vom Nutzer eingegebenen Code. [`POST /v1/verify/verifications/next-channel`](/docs/api/reference/create-verification-next-channel) sendet einen neuen Code über den nächsten Kanal. | | Guide | [Verify-Übersicht](/docs/guides/verify/overview) und [Ihren ersten Kunden verifizieren](/docs/get-started/verify-your-first-customer) | ### Weitere Produkte | Produkt | Guide | Erster Aufruf | | -------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | WhatsApp | [WhatsApp-Übersicht](/docs/guides/whatsapp/overview) | [`POST /v1/whatsapp/messages`](/docs/api/reference/create-whatsapp-message) | | Apple Messages | [Apple Messages for Business – Guides](/docs/guides/apple-messages) | [`POST /v1/amb/messages`](/docs/api/reference/create-amb-message) | | Voice | [Voice-Übersicht](/docs/guides/voice/overview) | [`POST /v1/voice/calls`](/docs/api/reference/create-voice-call) | | eSIM | [eSIM-Konnektivitätsguide](/docs/guides/esim/overview) | [`POST /v1/esim/orders`](/docs/api/reference/create-esim-order) | | Realtime | [Realtime-Übersicht](/docs/guides/realtime/overview) | [`POST /v1/realtime/apps/{realtime_app_id}/events`](/docs/api/reference/publish-realtime-app-event) | | Numbers | [Numbers-Übersicht](/docs/guides/numbers/overview) | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers) | | Lookup | [Lookup-Übersicht](/docs/guides/lookup/overview) | [`POST /v1/lookup/phone-number`](/docs/api/reference/create-phone-number-lookup) | | Webhooks | [Webhooks & Events](/docs/guides/webhooks) | [`POST /v1/webhooks`](/docs/api/reference/create-webhook) | ## 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](/docs/api/regions). - **Authentifizierung**: Requests übermitteln einen API-Schlüssel als Bearer-Token: `Authorization: Bearer bk_us1_...`. Siehe [Authentifizierung](/docs/api/authentication). - **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](/docs/api/errors). - **Paginierung**: Listen-Endpoints verwenden cursorbasierte Paginierung mit einem gemeinsamen Parametersatz. Siehe [Paginierung](/docs/api/pagination). - **Idempotenz**: Mutierende Endpoints akzeptieren einen `Idempotency-Key`-Header, damit Wiederholungsversuche sicher sind. Siehe [Idempotency-Key-Header](/docs/api/idempotency). - **Deprecations**: Ein umbenanntes Feld funktioniert weiterhin unter seinem alten Namen, und eine Response zeigt dies mit einem `Deprecation`-Header an. Siehe [Deprecations](/docs/api/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](/docs/sdks/typescript), Go und Python: typisierte Methoden über die kuratierte öffentliche Oberfläche - Die [Bird CLI](/docs/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](https://bird.com/postman/bird-api.postman_collection.json) und ein Environment für [us1](https://bird.com/postman/bird-api-us1.postman_environment.json) oder [eu1](https://bird.com/postman/bird-api-eu1.postman_environment.json) direkt herunterladen. ## Weiterlesen - [Authentifizierung](/docs/api/authentication): wie sich Requests auf Wire-Ebene authentifizieren - [Basis-URLs und Regionen](/docs/api/regions): regionale Hosts und das Regionsmodell - [Paginierung](/docs/api/pagination): Cursor, Seitengrößen und Sortierung - [Idempotency-Key-Header](/docs/api/idempotency): sichere Wiederholungsversuche für mutierende Requests - [Fehlerantworten](/docs/api/errors): die Fehlerantwort-Struktur und der vollständige Fehlerkatalog - [Deprecations](/docs/api/deprecations): was ein abgelöstes Feld weiterhin tut und wie Sie davon migrieren ## Related resources - [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer) - [Build your first integration](/learn/paths/integration) (course) [Get an implementation brief](/learn/workspace?topic=api-basics)