Documentation
Sign inGet Started
Commencer
Guides
Référence API
SDK
CLI
Base de connaissances
Changelog

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, Voice, Realtime, Verify, et les outils pour développeurs (Webhooks et Documentation, l'API de recherche dans la documentation). Les autres endpoints publics, notamment les domaines d'envoi, l'e-mail entrant, les contacts et audiences, et WhatsApp, sont accessibles via la recherche et les liens profonds dans leurs guides. Voice est ajouté à la API une ressource à la fois, en commençant par le journal d'appels ; les lectures de trunk, d'identifiant d'appelant, de destination et de statistiques restent disponibles dans le tableau de bord et la CLI en attendant. Les paramètres de l'espace de travail, les clés API et les IP dédiées se gèrent 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.

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 : l'API n'utilise jamais PUT. Une requête PATCH ne modifie que les champs que vous incluez ; les champs omis restent inchangés.
  • 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.
Run in Postman
Vous pouvez également télécharger la collection et un environnement pour us1 ou eu1 directement.

À lire ensuite

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Comprendre le conceptShould I use a Bird SDK or call the API directly?Suivre le parcours d'apprentissageBuild your first integrationGuide d'implémentationSend your first email
Obtenir un guide d'implémentation