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, Voice, Realtime, Verify, en de ontwikkelaarstools (Webhooks en Documentation, de API voor het doorzoeken van de documentatie). Andere openbare endpoints, waaronder verzendende domeinen, inkomende e-mail, contacten en doelgroepen, en WhatsApp, zijn bereikbaar via zoeken en de directe links in hun gidsen. 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.
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-verzoek wijzigt alleen de velden die je meestuurt; weggelaten velden blijven 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.
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
Gerelateerde bronnen
Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.