Introductie

De Bird API is een uniforme REST API voor alles wat het platform doet. Deze referentie documenteert elk publiek endpoint, gegenereerd uit dezelfde OpenAPI-specificatie die de officiële SDK's aanstuurt, zodat de request- en responsestructuren hier exact overeenkomen met wat er over de lijn gaat.

De referentiesidebar groepeert de meestgebruikte resources per product: Email, SMS, WhatsApp, Apple Messages, Voice, eSIM, Realtime, Verify, Preferences, Numbers, Lookup, Workspace, en de ontwikkelaarstools (Webhooks en Documentation, de API voor het doorzoeken van de documentatie). Verzenddomeinen, inkomende e-mail, en contacten en doelgroepen hebben referentiepagina's zonder sidebar-vermelding. Begin bij Maak een verzenddomein aan, Maak een inkomend adres aan, Maak een contact aan en Maak een doelgroep aan, of vanuit hun gidsen: Verzenddomeinen, E-mail ontvangen, Contacten en Doelgroepen. De sectie Voice bevat gesprekken, leg logs, trunks, nummers, beller-ID's, bestemmingen en SIP-sessiereferenties. Voice-statistieken blijven beschikbaar via het dashboard en CLI. Werkruimte-instellingen, API-sleutels en dedicated IP's worden beheerd in het dashboard, niet via de openbare API.

Resourcepagina's zijn via deeplinks gekoppeld vanuit de gidsen: als een gids een endpoint noemt, landt de link op de bijbehorende referentie-entry hier.

Voor coding agents

Wijs een agent naar deze machineleesbare bronnen:

• OpenAPI-specificatie: elk publiek endpoint, schema en foutcode, ook beschikbaar als YAML. De SDK's worden uit hetzelfde bestand gegenereerd.
• API-index: de API-gidsen, elke operatiereferentie en de openbare fouten, gegroepeerd per product en gelinkt naar hun Markdown-pagina's.
• Docs-index: elke gepubliceerde Engelstalige documentatiepagina, gegroepeerd per sectie en product.
• Site-index: producten, quickstarts en agent-tooling op bird.com.
• MCP server: gehoste tools op mcp.bird.com die na een browseraanmelding op je werkruimte werken.
• Bird CLI: de API vanuit een terminal. CLI for agents behandelt de JSON-output en exitcodes.
• Markdown-pagina's: voeg .md toe aan een willekeurige docs-URL, zoals in https://bird.com/docs/api.md, of verstuur Accept: text/markdown.

Productoverzicht

Elke tabel toont de aanroepen die een integratie doet, op volgorde, met een link naar de referentiepagina van elke aanroep en naar de gidsen van het product.

Email

SMS

Verify

Overige producten

Conventies

Elk endpoint volgt dezelfde conventies. Ze staan hier één keer beschreven in plaats van herhaald op elke pagina.

• Basispad: alle endpoints bevinden zich onder /v1 op een regionale host zoals https://us1.platform.bird.com. Zie Basis-URL's en regio's.
• Authenticatie: requests bevatten een API-sleutel als bearer token: Authorization: Bearer bk_us1_.... Zie Authenticatie.
• JSON, snake_case: request- en responsebodies zijn JSON met snake_case-veldnamen (created_at, workspace_id), en requests moeten Content-Type: application/json instellen.
• Timestamps: alle timestamps zijn RFC 3339-strings in UTC, in velden met het achtervoegsel _at (created_at, delivered_at). Resourcetimestamps zoals created_at worden door de server toegekend en zijn alleen-lezen. Enkele requestvelden, zoals scheduled_at, zijn timestamps die je zelf opgeeft.
• Getypeerde resource-ID's: elk ID draagt een typeprefix: em_ voor e-mailberichten, dom_ voor verzenddomeinen, whk_ voor webhook-endpoints, sup_ voor suppressies, enzovoort. De prefix maakt een ID zelfbeschrijvend in logs en voorkomt dat je het ID van de ene resource doorgeeft waar dat van een andere wordt verwacht.
• Gedeeltelijke updates gebruiken PATCH: een PATCH-request wijzigt alleen de velden die je meestuurt en laat weggelaten velden ongewijzigd. Een paar subresources die je op naam in de URL aanspreekt, worden geschreven met PUT, wat die subresource volledig vervangt.
• Queryparameters zijn strikt: een request met een queryparameter die het endpoint niet documenteert, wordt afgewezen met 422 (E01029) in plaats van genegeerd. Controleer de spelling aan de hand van de parameterlijst van het endpoint.
• Fouten: elke foutresponse bevat hetzelfde foutantwoord, met een type voor grove vertakking, een stabiele code, een leesbare message, en de request_id om te vermelden bij contact met support. Zie Foutresponses.
• Paginering: lijstendpoints gebruiken cursorgebaseerde paginering met een gedeelde parameterset. Zie Paginering.
• Idempotentie: muterende endpoints accepteren een Idempotency-Key-header zodat opnieuw proberen veilig is. Zie Idempotency-Key-header.
• Deprecaties: een hernoemd veld blijft werken onder zijn oude naam, en een response geeft dat aan met een Deprecation-header. Zie Deprecaties.

Aanbevolen clients

Je kunt de API met elke HTTP-client aanroepen, maar de officiële clients regelen authenticatie, regioselectie, opnieuw proberen en paginering voor je:

• De officiële SDK's voor TypeScript, Go en Python: getypeerde methoden over het samengestelde publieke oppervlak
• De Bird CLI: de API vanuit je terminal, ook geschikt voor scripts en agents

Uitvoeren in Postman

De volledige API is ook beschikbaar als Postman-collectie, geconverteerd uit dezelfde specificatie, met een voorbeeldrequest en -response op elk endpoint. Importeer de omgeving voor je regio, stel apiKey in op een werkruimte-API-sleutel en verstuur een willekeurig request.

Je kunt ook de collectie en een omgeving voor us1 of eu1 rechtstreeks downloaden.

Lees verder

• Authenticatie: hoe requests zich authenticeren op protocolniveau
• Basis-URL's en regio's: regionale hosts en het regiomodel
• Paginering: cursors, paginagroottes en sortering
• Idempotency-Key-header: veilig opnieuw proberen voor muterende requests
• Foutresponses: het foutantwoord en de volledige foutcatalogus
• Deprecaties: wat een vervangen veldnaam nog doet, en hoe je ervan migreert