Introdução

A Bird API é uma REST API unificada para tudo o que a plataforma faz. Esta referência documenta todos os endpoints públicos, gerada a partir da mesma especificação OpenAPI que alimenta os SDKs oficiais, de modo que os formatos de requisição e resposta aqui são exatamente o que trafega na rede.

A barra lateral da referência agrupa os recursos mais usados por produto: Email, SMS, WhatsApp, Apple Messages, Voice, eSIM, Realtime, Verify, Preferences, Numbers, Lookup, Workspace e as ferramentas para desenvolvedores (Webhooks e Documentation, a API de busca na documentação). Domínios de envio, e-mail de entrada, e contatos e audiências possuem páginas de referência sem entrada na barra lateral. Comece por Criar um domínio de envio, Criar um endereço de entrada, Criar um contato e Criar uma audiência, ou pelos respectivos guias: Domínios de envio, Recebimento de e-mail, Contatos e Audiências. A seção Voice inclui chamadas, logs de pernas de chamada, troncos, números, identificadores de chamada, destinos e credenciais de sessão SIP. As estatísticas de voz continuam disponíveis pelo painel e por CLI. Configurações do espaço de trabalho, chaves API e IPs dedicados são gerenciados no painel, não na API pública.

As páginas de recurso possuem links diretos a partir dos guias: quando um guia menciona um endpoint, o link leva à entrada correspondente nesta referência.

Para agentes de código

Aponte um agente para estas fontes legíveis por máquina:

• Especificação OpenAPI: todos os endpoints públicos, schemas e códigos de erro, também disponível em YAML. Os SDKs são gerados a partir do mesmo arquivo.
• Índice API: os guias API, todas as referências de operação e os erros públicos, agrupados por produto e vinculados às suas páginas Markdown.
• Índice da documentação: todas as páginas de documentação publicadas em inglês, agrupadas por seção e produto.
• Índice do site: produtos, quickstarts e ferramentas para agentes em bird.com.
• MCP server: ferramentas hospedadas em mcp.bird.com que atuam no seu espaço de trabalho após login pelo navegador.
• Bird CLI: a API a partir de um terminal. CLI para agentes cobre sua saída JSON e códigos de saída.
• Páginas Markdown: acrescente .md a qualquer URL da documentação, como em https://bird.com/docs/api.md, ou envie Accept: text/markdown.

Mapa de produtos

Cada tabela lista as chamadas que uma integração faz, em ordem, com um link para a página de referência de cada chamada e para os guias do produto.

Email

SMS

Verify

Outros produtos

Convenções

Todo endpoint segue as mesmas convenções. Elas são declaradas uma vez aqui, em vez de repetidas em cada página.

• Caminho base: todos os endpoints residem em /v1 em um host regional como https://us1.platform.bird.com. Veja URLs base e regiões.
• Autenticação: as requisições levam uma chave API como bearer token: Authorization: Bearer bk_us1_.... Veja Autenticação.
• JSON, snake_case: os corpos de requisição e resposta são JSON com nomes de campo em snake_case (created_at, workspace_id), e as requisições devem definir Content-Type: application/json.
• Timestamps: todos os timestamps são strings RFC 3339 em UTC, em campos com sufixo _at (created_at, delivered_at). Timestamps de recurso como created_at são atribuídos pelo servidor e somente leitura. Alguns campos de requisição, como scheduled_at, são timestamps fornecidos por você.
• IDs de recurso tipados: todo ID carrega um prefixo de tipo: em_ para mensagens de e-mail, dom_ para domínios de envio, whk_ para endpoints de webhook, sup_ para supressões, e assim por diante. O prefixo torna o ID autodescritivo nos logs e impede que o ID de um recurso seja passado no lugar de outro.
• Atualizações parciais usam PATCH: uma requisição PATCH altera apenas os campos que você incluir e mantém os campos omitidos inalterados. Alguns sub-recursos endereçados pelo nome na URL são escritos com PUT, que substitui esse sub-recurso por completo.
• Parâmetros de query são estritos: uma requisição que carrega um parâmetro de query não documentado pelo endpoint é rejeitada com 422 (E01029), em vez de ignorada. Verifique a grafia na lista de parâmetros do endpoint.
• Erros: toda resposta de erro carrega a mesma resposta de erro, com um type para ramificação geral, um code estável, uma message legível por humanos e o request_id para citar ao contatar o suporte. Veja Respostas de erro.
• Paginação: endpoints de listagem usam paginação baseada em cursor com um conjunto compartilhado de parâmetros. Veja Paginação.
• Idempotência: endpoints de mutação aceitam um header Idempotency-Key para que novas tentativas sejam seguras. Veja Header Idempotency-Key.
• Depreciações: um campo renomeado continua funcionando com o nome antigo, e a resposta indica isso com um header Deprecation. Veja Depreciações.

Clientes recomendados

Você pode chamar a API com qualquer cliente HTTP, mas os clientes oficiais cuidam de autenticação, seleção de região, novas tentativas e paginação para você:

• Os SDKs oficiais para TypeScript, Go e Python: métodos tipados sobre a superfície pública curada
• A Bird CLI: a API a partir do seu terminal, também adequada para scripts e agentes

Execute no Postman

A API completa também é uma coleção do Postman, convertida a partir desta mesma especificação, com um exemplo de requisição e resposta em cada endpoint. Importe o ambiente para a sua região, defina apiKey com uma chave API do espaço de trabalho e envie qualquer requisição.

Você também pode baixar a coleção e um ambiente para us1 ou eu1 diretamente.

Leia a seguir

• Autenticação: como as requisições se autenticam no nível da rede
• URLs base e regiões: hosts regionais e o modelo de regiões
• Paginação: cursores, tamanhos de página e ordenação
• Header Idempotency-Key: novas tentativas seguras para requisições de mutação
• Respostas de erro: a resposta de erro e o catálogo completo de erros
• Depreciações: o que um campo substituído ainda faz e como migrar dele