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, WhatsApp, Apple Messages, Voice, eSIM, Realtime, Verify, Preferences, Numbers, Lookup, Workspace y las herramientas para desarrolladores (Webhooks y Documentation, el API de búsqueda en la documentación). Los dominios de envío, el correo entrante, y los contactos y audiencias tienen páginas de referencia sin entrada en la barra lateral. Empieza desde Crear un dominio de envío, Crear una dirección de entrada, Crear un contacto y Crear una audiencia, o desde sus guías: Dominios de envío, Recibir correo, Contactos y Audiencias. 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.

Para agentes de código

Apunta un agente a estas fuentes legibles por máquina:

• Especificación OpenAPI: cada endpoint público, esquema y código de error, también disponible como YAML. Los SDKs se generan a partir del mismo archivo.
• Índice de API: las guías de API, cada referencia de operación y los errores públicos, agrupados por producto y enlazados a sus páginas Markdown.
• Índice de documentación: cada página de documentación publicada en inglés, agrupada por sección y producto.
• Índice del sitio: productos, quickstarts y herramientas para agentes en bird.com.
• MCP server: herramientas alojadas en mcp.bird.com que actúan sobre tu espacio de trabajo tras iniciar sesión en el navegador.
• Bird CLI: la API desde una terminal. CLI for agents cubre su salida JSON y códigos de salida.
• Páginas Markdown: añade .md a cualquier URL de la documentación, como en https://bird.com/docs/api.md, o envía Accept: text/markdown.

Mapa de productos

Cada tabla enumera las llamadas que realiza una integración, en orden, con un enlace a la página de referencia de cada llamada y a las guías del producto.

Email

SMS

Verify

Otros productos

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 y deja intactos los campos omitidos. 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 estructura, 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.

También puedes descargar la colección y un entorno para us1 o eu1 directamente.

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