Introduction

L'Bird API est une REST API unifiée couvrant tout ce que la plateforme propose. Cette référence documente chaque endpoint public, générée à partir de la même spécification OpenAPI qui alimente les SDK officiels : les formats de requête et de réponse présentés ici sont exactement ceux qui transitent sur le réseau.

La barre latérale de la référence regroupe les ressources les plus utilisées par produit : Email, SMS, WhatsApp, Apple Messages, Voice, eSIM, Realtime, Verify, Preferences, Numbers, Lookup, Workspace, et les outils pour développeurs (Webhooks et Documentation, l'API de recherche dans la documentation). Les domaines d'envoi, l'e-mail entrant, et les contacts et audiences disposent de pages de référence sans entrée dans la barre latérale. Commencez par Créer un domaine d'envoi, Créer une adresse entrante, Créer un contact et Créer une audience, ou par leurs guides : Domaines d'envoi, Réception d'e-mails, Contacts et Audiences. La section Voice comprend les appels, les journaux de legs, les trunks, les numéros, les identifiants d'appelant, les destinations et les identifiants de session SIP. Les statistiques Voice restent disponibles via le tableau de bord et CLI. Les paramètres de l'espace de travail, les clés API et les IP dédiées sont gérés dans le tableau de bord plutôt que dans l'API publique.

Les pages de ressources sont liées en profondeur depuis les guides : lorsqu'un guide mentionne un endpoint, le lien mène directement à son entrée dans cette référence.

Pour les agents de programmation

Orientez un agent vers ces sources lisibles par machine :

• Spécification OpenAPI : chaque endpoint public, schéma et code d'erreur, également disponible en YAML. Les SDK sont générés à partir du même fichier.
• Index API : les guides API, chaque référence d'opération et les erreurs publiques, regroupés par produit et liés à leurs pages Markdown.
• Index de la documentation : chaque page de documentation publiée en anglais, regroupée par section et par produit.
• Index du site : produits, guides de démarrage rapide et outils pour agents sur bird.com.
• Serveur MCP : outils hébergés sur mcp.bird.com qui agissent sur votre espace de travail après une connexion via le navigateur.
• Bird CLI : l'API depuis un terminal. CLI pour les agents couvre sa sortie JSON et ses codes de sortie.
• Pages Markdown : ajoutez .md à n'importe quelle URL de la documentation, comme dans https://bird.com/docs/api.md, ou envoyez Accept: text/markdown.

Carte des produits

Chaque tableau liste les appels effectués par une intégration, dans l'ordre, avec un lien vers la page de référence de chaque appel et vers les guides du produit.

Email

SMS

Verify

Autres produits

Conventions

Chaque endpoint suit les mêmes conventions. Elles sont énoncées une seule fois ici plutôt que répétées sur chaque page.

• Chemin de base : tous les endpoints se trouvent sous /v1 sur un hôte régional tel que https://us1.platform.bird.com. Voir URL de base et régions.
• Authentification : les requêtes transmettent une clé API en tant que bearer token : Authorization: Bearer bk_us1_.... Voir Authentification.
• JSON, snake_case : les corps de requête et de réponse sont en JSON avec des noms de champs en snake_case (created_at, workspace_id), et les requêtes doivent définir Content-Type: application/json.
• Horodatages : tous les horodatages sont des chaînes RFC 3339 en UTC, dans des champs suffixés par _at (created_at, delivered_at). Les horodatages de ressource comme created_at sont attribués par le serveur et en lecture seule. Quelques champs de requête, comme scheduled_at, sont des horodatages que vous fournissez.
• ID de ressource typés : chaque ID porte un préfixe de type : em_ pour les messages e-mail, dom_ pour les domaines d'envoi, whk_ pour les endpoints de webhook, sup_ pour les suppressions, etc. Le préfixe rend un ID auto-descriptif dans les logs et empêche de passer l'ID d'une ressource là où celui d'une autre est attendu.
• Les mises à jour partielles utilisent PATCH : une requête PATCH ne modifie que les champs que vous incluez et laisse les champs omis inchangés. Quelques sous-ressources que vous désignez par nom dans l'URL s'écrivent avec PUT, qui remplace cette sous-ressource en totalité.
• Les paramètres de requête sont stricts : une requête contenant un paramètre de requête non documenté par l'endpoint est rejetée avec 422 (E01029) au lieu d'être ignorée. Vérifiez l'orthographe en vous référant à la liste des paramètres de l'endpoint.
• Erreurs : chaque réponse d'erreur utilise la même enveloppe, avec un type pour le branchement général, un code stable, un message lisible par un humain, et le request_id à citer lorsque vous contactez le support. Voir Réponses d'erreur.
• Pagination : les endpoints de liste utilisent une pagination par curseur avec un jeu de paramètres commun. Voir Pagination.
• Idempotence : les endpoints de mutation acceptent un en-tête Idempotency-Key pour que les nouvelles tentatives soient sûres. Voir En-tête Idempotency-Key.
• Dépréciations : un champ renommé continue de fonctionner sous son ancien nom, et la réponse le signale avec un en-tête Deprecation. Voir Dépréciations.

Clients recommandés

Vous pouvez appeler l'API avec n'importe quel client HTTP, mais les clients officiels gèrent pour vous l'authentification, la sélection de région, les nouvelles tentatives et la pagination :

• Les SDK officiels pour TypeScript, Go et Python : des méthodes typées couvrant la surface publique organisée
• Le Bird CLI : l'API depuis votre terminal, également adapté aux scripts et aux agents

Exécuter dans Postman

L'intégralité de l'API est également disponible sous forme de collection Postman, convertie à partir de cette même spécification, avec un exemple de requête et de réponse pour chaque endpoint. Importez l'environnement correspondant à votre région, définissez apiKey avec une clé API de l'espace de travail, et envoyez n'importe quelle requête.

Vous pouvez également télécharger la collection et un environnement pour us1 ou eu1 directement.

À lire ensuite

• Authentification : comment les requêtes s'authentifient au niveau du réseau
• URL de base et régions : hôtes régionaux et modèle de régions
• Pagination : curseurs, tailles de page et tri
• En-tête Idempotency-Key : nouvelles tentatives sûres pour les requêtes de mutation
• Réponses d'erreur : la réponse d'erreur et le catalogue complet des erreurs
• Dépréciations : ce que fait encore un nom de champ remplacé, et comment migrer