Autenticação da API

A API pública do TheAlert permite gerenciar monitores, consultar histórico de checks e muito mais de forma programática. Esta página explica como obter e usar sua chave de API.

Base URL

Todos os endpoints da API são prefixados com:

https://api.thealert.io/api/v1

Gerando uma chave de API

1. Acesse o Dashboard do TheAlert
2. Vá em "Integrações" → "API Keys"
3. Clique em "Nova Chave"
4. Dê um nome descritivo à chave (ex: CI/CD Pipeline, Script de Backup, Terraform)
5. A chave será exibida uma única vez — copie e armazene em local seguro imediatamente

As chaves têm o prefixo ta_:

ta_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Autenticando requisições

Há duas formas de passar a chave nas requisições — use qualquer uma:

Header Authorization (recomendado)

curl https://api.thealert.io/api/v1/monitors \
  -H "Authorization: Bearer ta_sua_chave_aqui"

Header X-API-Key

curl https://api.thealert.io/api/v1/monitors \
  -H "X-API-Key: ta_sua_chave_aqui"

Ambos os métodos são equivalentes e aceitos em todos os endpoints.

Rate limits por plano

Headers de rate limit

Toda resposta da API inclui os seguintes headers:

Exemplo de resposta com headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1741712400

Quando o limite é atingido, a API retorna 429 Too Many Requests:

{
  "error": "Rate limit exceeded",
  "retryAfter": 1741712400
}

Formato de resposta

Todas as respostas bem-sucedidas retornam JSON com Content-Type: application/json.

Resposta de sucesso

{
  "data": { ... },
  "meta": { ... }
}

Resposta de erro

{
  "error": "Monitor not found",
  "code": "NOT_FOUND"
}

Códigos de status HTTP

Gerenciando chaves

Revogar uma chave

Para revogar uma chave comprometida ou desnecessária:

1. Integrações → API Keys
2. Encontre a chave → clique em "Revogar"
3. A chave para de funcionar imediatamente

Boas práticas de segurança

Nunca comite chaves de API em repositórios Use variáveis de ambiente ou serviços de gerenciamento de secrets (AWS Secrets Manager, Vault, GitHub Secrets).

Crie chaves separadas por contexto Uma chave para CI/CD, outra para scripts locais, outra para integrações. Assim, se uma for comprometida, você revoga apenas ela sem afetar os outros sistemas.

Rotacione chaves periodicamente Revogue e recrie as chaves a cada 90 dias como boa prática de segurança.

Exemplo completo

# Listar todos os monitores
curl https://api.thealert.io/api/v1/monitors \
  -H "Authorization: Bearer ta_sua_chave_aqui" \
  -H "Accept: application/json"

Próximos passos

• API de Monitores →
• Histórico de Checks →
• API de Heartbeat →