# Tá Rodando — API para agentes (v1)

Monitoramento de serviços HTTP com status page em português. Esta referência é escrita pra um agente de IA (ou um humano com pressa) ler e agir.

Formato: JSON. Erros voltam { "error": "<codigo>", "message": "<o que houve e o que fazer>" }.

- Base URL: `https://tarodando.com.br/api/v1`
- Autenticação: header `Authorization: Bearer trd_live_...`
- Como obter a chave: peça ao humano — painel em https://tarodando.com.br/app/plano, seção "Chaves de API". Sem conta? Login por email ou GitHub em https://tarodando.com.br/entrar (grátis, sem cartão).
- Grátis: 3 monitores ativos, checagem a cada 5 ou 15 min.
- Pro (R$79/mês): 10 monitores, checagem a cada 1 min.

## Criar monitor

`POST /monitors`

Cria um monitor HTTP e roda o primeiro check na hora — o corpo do 201 já reflete o resultado.

```bash
curl -X POST https://tarodando.com.br/api/v1/monitors \
  -H "Authorization: Bearer trd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.exemplo.com.br/healthcheck",
    "name": "API",
    "intervalMin": 5,
    "section": "Backend"
  }'
```

Campos do corpo: `url` (string, obrigatório — endereço público a monitorar — IPs privados são recusados), `name` (string, opcional — derivado da URL se omitido), `intervalMin` (int, opcional — padrão 5; grátis aceita 5 ou 15, Pro também 1), `section` (string, opcional — nome do agrupamento na página — casa com seção existente ou cria).

Resposta `201`:

```json
{
  "monitor": {
    "id": "cm9x1a2b3c4d5e6f7g8h9i0j1",
    "name": "API",
    "url": "https://app.exemplo.com.br/healthcheck",
    "intervalMin": 5,
    "status": "operational",
    "lastStatus": "ok",
    "lastCheckedAt": "2026-07-16T12:00:00.000Z",
    "section": "Backend",
    "paused": false,
    "createdAt": "2026-07-16T12:00:00.000Z",
    "statusPage": "https://exemplo.tarodando.com.br"
  }
}
```

URL fora do ar vem com lastStatus: "fail" (não null). lastStatus: null só acontece se o check não pôde nem rodar (erro interno raro) — nesse caso, consulte GET /monitors/{id}. A status page pública fica em statusPage.

## Listar monitores

`GET /monitors`

Lista todos os monitores da conta, no mesmo shape do criar.

```bash
curl -X GET https://tarodando.com.br/api/v1/monitors \
  -H "Authorization: Bearer trd_live_..."
```

Resposta `200`:

```json
{
  "monitors": [
    {
      "id": "cm9x1a2b3c4d5e6f7g8h9i0j1",
      "name": "API",
      "url": "https://app.exemplo.com.br/healthcheck",
      "intervalMin": 5,
      "status": "operational",
      "lastStatus": "ok",
      "lastCheckedAt": "2026-07-16T12:00:00.000Z",
      "section": "Backend",
      "paused": false,
      "createdAt": "2026-07-16T12:00:00.000Z",
      "statusPage": "https://exemplo.tarodando.com.br"
    }
  ]
}
```

paused: true = monitor além do teto do plano, não está sendo checado. url pode ser null em componentes legados criados manualmente (sem monitoramento) — trate como opcional.

## Detalhe de um monitor

`GET /monitors/{id}`

Um monitor + resultado da última checagem.

```bash
curl -X GET https://tarodando.com.br/api/v1/monitors/cm9x1a2b3c4d5e6f7g8h9i0j1 \
  -H "Authorization: Bearer trd_live_..."
```

Parâmetros de rota: `id` (string, obrigatório — id do monitor).

Resposta `200`:

```json
{
  "monitor": {
    "id": "cm9x1a2b3c4d5e6f7g8h9i0j1",
    "name": "API",
    "url": "https://app.exemplo.com.br/healthcheck",
    "intervalMin": 5,
    "status": "operational",
    "lastStatus": "ok",
    "lastCheckedAt": "2026-07-16T12:00:00.000Z",
    "section": "Backend",
    "paused": false,
    "createdAt": "2026-07-16T12:00:00.000Z",
    "statusPage": "https://exemplo.tarodando.com.br"
  },
  "lastCheck": {
    "ok": true,
    "latencyMs": 123,
    "error": null,
    "checkedAt": "2026-07-16T12:00:00.000Z"
  }
}
```

lastCheck: null = nunca checado.

## Atualizar monitor

`PATCH /monitors/{id}`

Corpo com qualquer subconjunto dos campos abaixo. Campos ausentes não mudam.

```bash
curl -X PATCH https://tarodando.com.br/api/v1/monitors/cm9x1a2b3c4d5e6f7g8h9i0j1 \
  -H "Authorization: Bearer trd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API pública",
    "intervalMin": 15
  }'
```

Parâmetros de rota: `id` (string, obrigatório — id do monitor).

Campos do corpo: `name` (string, opcional — novo nome), `url` (string, opcional — nova URL (mesma validação do criar)), `intervalMin` (int, opcional — novo intervalo (limites do plano valem)), `section` (string | null, opcional — null remove da seção).

Resposta `200`:

```json
{
  "monitor": {
    "id": "cm9x1a2b3c4d5e6f7g8h9i0j1",
    "name": "API",
    "url": "https://app.exemplo.com.br/healthcheck",
    "intervalMin": 5,
    "status": "operational",
    "lastStatus": "ok",
    "lastCheckedAt": "2026-07-16T12:00:00.000Z",
    "section": "Backend",
    "paused": false,
    "createdAt": "2026-07-16T12:00:00.000Z",
    "statusPage": "https://exemplo.tarodando.com.br"
  }
}
```

## Remover monitor

`DELETE /monitors/{id}`

Remove o monitor e o serviço correspondente da página.

```bash
curl -X DELETE https://tarodando.com.br/api/v1/monitors/cm9x1a2b3c4d5e6f7g8h9i0j1 \
  -H "Authorization: Bearer trd_live_..."
```

Parâmetros de rota: `id` (string, obrigatório — id do monitor).

Resposta `200`:

```json
{ "ok": true }
```

## Erros

| HTTP | error | quando |
|---|---|---|
| 401 | unauthorized | chave ausente, inválida ou revogada |
| 400 | invalid_body | corpo não é JSON |
| 422 | invalid_url / invalid_name / invalid_interval | validação — a message diz o que corrigir |
| 403 | plan_limit | teto de monitores do plano atingido — upgrade ou remova um |
| 404 | not_found / no_page | id inexistente nesta conta / conta sem página (onboarding pendente) |

## O que a API v1 NÃO faz

Incidentes, canais de aviso (WhatsApp/Telegram/Slack…) e assinantes são geridos no painel: https://tarodando.com.br/app.