> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Referência da API

> API REST pública v1, camadas de compatibilidade e ingestão de webhooks.

Bem-vindo à referência da API do Switchbord. O Switchbord oferece uma API REST pública estável (v1) para gerenciamento de workspaces, sincronização de contatos e envio de mensagens, além de camadas de compatibilidade especializadas para integrações legadas.

## Primeiros passos

A API está acessível em `https://api.switchbord.ai/v1` (ou no seu domínio auto-hospedado). Todas as requisições devem ser autenticadas usando uma API Key enviada no header `X-API-Key`.

Você pode gerenciar as API Keys na seção **Settings > Integrations > API Keys** do painel do Switchbord.

## Superfície principal v1

A API v1 é focada em operações de alto nível para workflows automatizados:

* `GET /v1/contacts` - Lista e filtra contatos do workspace.
* `POST /v1/messages` - Envia mensagens (texto, mídia ou template) para um contato.
* `GET /v1/templates` - Busca templates aprovados do WhatsApp.
* `POST /v1/broadcasts` - Dispara um broadcast pré-definido para um segmento.

## Ingestão de Webhook do Provider

O Switchbord lida com toda a complexidade dos desafios de webhook da Meta e da verificação de assinatura:

* `POST /webhooks/whatsapp` - Ingestão principal para eventos da WhatsApp Business Platform.

Essas rotas tratam a verificação de challenge, a validação de assinatura e o enfileiramento de jobs seguro contra replay.

## Endpoints de compatibilidade

Para facilitar a migração de sistemas legados, mantemos aliases de compatibilidade para o Charles e outras plataformas comuns:

* `PUT /api/v1beta/contact/`
* `POST /webhooks/v0/rest-trigger/...`

Consulte o guia [Superfície de Compatibilidade](/pt-BR/api-reference/compatibility) para ver os mapeamentos exatos.

## API interna e de extensão

Para operações forenses e administrativas, existe uma superfície de API interna (com o prefixo `/internal`). Esses endpoints são usados pela interface do Switchbord e estão sujeitos a alterações.

* `GET /internal/audit-logs`
* `GET /internal/webhook-events`

## Postura e confiabilidade

* **Totalmente tipada:** Todos os endpoints são modelados com TypeScript e validados na borda (edge).
* **Fila em primeiro lugar (Queue-First):** Os payloads de webhook são persistidos no banco de dados e normalizados antes de serem processados por workers em segundo plano.
* **Limitação de taxa (Rate Limiting):** Limites padrão se aplicam aos endpoints v1. Contate o suporte para necessidades de alto volume.