← Pulse

API do Pulse

Automatize criação de checks, configuração de canais e leitura de pings/alertas. Mesma API que o dashboard usa, autenticada por Personal Access Token.

Base URL

https://api.pulsebr.app

Autenticação

Crie um Personal Access Token em /app/api-tokens. O plaintext aparece uma única vez na criação — copie e guarde com segurança.

Inclua em todas as requisições:

Authorization: Bearer pulse_pat_<seu-token>

O token carrega contexto da organização — você não precisa enviar X-Pulso-Org.

Listar checks

GET /api/checks
curl https://api.pulsebr.app/api/checks \
  -H "Authorization: Bearer pulse_pat_..."

Resposta:

{
  "items": [
    {
      "id": "9ae7246a-295b-...",
      "name": "Backup test",
      "status": "up",
      "schedule_kind": "simple",
      "simple_interval_seconds": 60,
      "grace_period_seconds": 120,
      "last_ping_at": "2026-05-08T22:08:42.036Z",
      "next_expected_at": "2026-05-08T22:09:42.036Z"
    }
  ],
  "next_cursor": null
}

Criar check

POST /api/checks
curl -X POST https://api.pulsebr.app/api/checks \
  -H "Authorization: Bearer pulse_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backup diário",
    "schedule_kind": "simple",
    "simple_interval_seconds": 86400,
    "grace_period_seconds": 3600
  }'

Resposta:

{
  "id": "uuid-aqui",
  "ping_url": "https://api.pulsebr.app/ping/uuid-aqui",
  "status": "new",
  ...
}

Para schedule cron, use {"schedule_kind":"cron","cron_expression":"0 3 * * *","cron_timezone":"America/Sao_Paulo"}.

Detalhe do check

GET /api/checks/:id

Retorna o check + 100 últimos pings + 20 alertas recentes + snippets de integração (curl, bash, node, python, php).

Pause / resume / delete

PATCH /api/checks/:id  body: {"action":"pause"}  ou  {"action":"resume"}
DELETE /api/checks/:id

Bater o ping (do seu cron)

GET /ping/:uuid             → sucesso
GET /ping/:uuid/start       → começou (detecta job travado)
GET /ping/:uuid/fail        → falhou
POST /ping/:uuid/:exitCode  → exitCode != 0 = falha (body opcional, até 10KB)

O endpoint /ping/* não exige autenticação — o UUID é a credencial. Limite de 100 req/min por UUID.

Canais de alerta

GET    /api/channels
POST   /api/channels       body: {"kind":"telegram","label":"Oncall","target":{"chat_id":12345}}
DELETE /api/channels/:id

Tipos: email, telegram, slack, discord, webhook.

MCP (Claude Desktop / Cursor)

O Pulse vem com um MCP server pronto. Adicione ao seu ~/.claude_desktop_config.json:

{
  "mcpServers": {
    "pulso": {
      "command": "npx",
      "args": ["-y", "@pulso/mcp"],
      "env": { "PULSE_PAT": "pulse_pat_..." }
    }
  }
}

Ferramentas expostas: create_check, list_checks, get_check, pause_check, resume_check, recent_pings, recent_alerts.

Erros

Toda resposta de erro segue RFC 7807 (problem+json):

{
  "type": "https://pulsebr.app/errors/pulso-validation-failed",
  "title": "Erro de validação",
  "status": 422,
  "code": "pulso.validation.failed",
  "instance": "/api/checks"
}