Introducción
La Bird API es una REST API unificada para todo lo que hace la plataforma. Esta referencia documenta cada endpoint público, generada a partir de la misma especificación OpenAPI que impulsa los SDKs oficiales, por lo que las estructuras de petición y respuesta aquí son exactamente lo que viaja por la red.
La barra lateral de la referencia agrupa los recursos más usados por producto: Email, SMS, Voice, Realtime, Verify y las herramientas para desarrolladores (Webhooks y Documentation, el API de búsqueda en la documentación). Otros endpoints públicos, como dominios de envío, correo entrante, contactos y audiencias, y WhatsApp, están disponibles a través de la búsqueda y los enlaces directos en sus guías. La sección Voice incluye llamadas, registros de tramos, trunks, números, identificadores de llamante, destinos y credenciales de sesión SIP. Las estadísticas de voz siguen disponibles a través del panel de control y CLI. La configuración del espacio de trabajo, las claves API y las IP dedicadas se gestionan en el panel de control en lugar de la API pública.
Las páginas de recursos están enlazadas directamente desde las guías: cuando una guía menciona un endpoint, el enlace lleva a su entrada en esta referencia.
Convenciones
Todos los endpoints siguen las mismas convenciones. Se describen una sola vez aquí en lugar de repetirse en cada página.
- Ruta base: todos los endpoints residen bajo /v1 en un host regional como https://us1.platform.bird.com. Consulta URLs base y regiones.
- Autenticación: las peticiones llevan una clave API como bearer token: Authorization: Bearer bk_us1_.... Consulta Autenticación.
- JSON, snake_case: los cuerpos de petición y respuesta son JSON con nombres de campo en snake_case (created_at, workspace_id), y las peticiones deben incluir Content-Type: application/json.
- Timestamps: todos los timestamps son cadenas RFC 3339 en UTC, en campos con sufijo _at (created_at, delivered_at). Los timestamps de recursos como created_at son asignados por el servidor y de solo lectura; unos pocos campos de petición, como scheduled_at, son timestamps que tú proporcionas.
- IDs de recurso tipados: cada ID lleva un prefijo de tipo: em_ para mensajes de correo, dom_ para dominios de envío, whk_ para endpoints de webhook, sup_ para supresiones, y así sucesivamente. El prefijo hace que un ID sea autodescriptivo en los logs y evita pasar el ID de un recurso donde se espera el de otro.
- Las actualizaciones parciales usan PATCH: una solicitud PATCH cambia solo los campos que incluyes; los campos omitidos quedan intactos. Algunos subrecursos que se direccionan por nombre en la URL se escriben con PUT, que reemplaza ese subrecurso por completo.
- Los parámetros de consulta son estrictos: una petición que lleve un parámetro de consulta no documentado por el endpoint se rechaza con 422 (E01029) en lugar de ignorarse. Verifica la ortografía contra la lista de parámetros del endpoint.
- Errores: cada respuesta de error lleva la misma respuesta de error, con un type para clasificación general, un code estable, un message legible por humanos y el request_id que debes citar al contactar a soporte. Consulta Respuestas de error.
- Paginación: los endpoints de listado usan paginación basada en cursor con un conjunto de parámetros compartido. Consulta Paginación.
- Idempotencia: los endpoints de mutación aceptan un header Idempotency-Key para que los reintentos sean seguros. Consulta Header Idempotency-Key.
- Deprecaciones: un campo renombrado sigue funcionando con su nombre anterior, y la respuesta lo indica con un header Deprecation. Consulta Deprecaciones.
Clientes recomendados
Puedes llamar a la API con cualquier cliente HTTP, pero los clientes oficiales se encargan de la autenticación, la selección de región, los reintentos y la paginación por ti:
- Los SDKs oficiales para TypeScript, Go y Python: métodos tipados sobre la superficie pública curada
- La Bird CLI: la API desde tu terminal, también adecuada para scripts y agentes
Ejecútalo en Postman
La API completa también es una colección de Postman, convertida a partir de esta misma especificación, con un ejemplo de petición y respuesta en cada endpoint. Importa el entorno de tu región, establece apiKey con una clave API del espacio de trabajo y envía cualquier petición.
Lectura siguiente
- Autenticación: cómo se autentican las peticiones a nivel de red
- URLs base y regiones: hosts regionales y el modelo de regiones
- Paginación: cursores, tamaños de página y ordenación
- Header Idempotency-Key: reintentos seguros para peticiones de mutación
- Respuestas de error: la respuesta de error y el catálogo completo de errores
- Deprecaciones: qué hace un nombre de campo reemplazado y cómo dejar de usarlo
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Comprender el conceptoShould I use a Bird SDK or call the API directly?Seguir la ruta de aprendizajeBuild your first integrationGuía de implementaciónSend your first email
Obtener un resumen de implementación