Rondas

Histórico de rondas#

As rondas da conta, da mais recente pra mais antiga, paginadas por cursor. risk_score + critical_count são o par que uma automação usa pra decidir se derruba o build; risk_label vai junto porque o número sozinho não é acionável.

O histórico respeita a retenção do plano (Pro: 365 dias · Business: sem limite). Rondas mais antigas não estão "na próxima página" — não existem mais.

Parâmetros de consulta

Requisição

curl https://api.guarita.dev/v1/public/scans?limit=20 \
  -H "Authorization: Bearer $GUARITA_API_KEY"

{
  "data": [
    {
      "id": "scan_7b3e9a12",
      "hostname": "app.exemplo.com.br",
      "status": "done",
      "created_at": "2026-08-27T14:02:56.902Z",
      "finished_at": "2026-08-27T14:09:24.106Z",
      "risk_score": 78,
      "risk_label": "HIGH_RISK",
      "critical_count": 2,
      "blocked": false
    },
    {
      "id": "scan_1c40de55",
      "hostname": "staging.exemplo.com.br",
      "status": "done",
      "created_at": "2026-08-21T11:15:03.517Z",
      "finished_at": "2026-08-21T11:19:42.204Z",
      "risk_score": 34,
      "risk_label": "MODERATE_RISK",
      "critical_count": 0,
      "blocked": false
    }
  ],
  "next_before": "2026-08-21T11:15:03.517Z"
}

Campos da resposta

Erros

• 400invalid_cursorbefore não é uma data ISO 8601.
• 401unauthorizedChave ausente, fora do formato Bearer gsk_…, inexistente, revogada — ou o plano da conta deixou de incluir a API. O corpo é o MESMO em todos os casos, de propósito. Vem com o header WWW-Authenticate.
• 403insufficient_scopeA chave é válida, mas não tem o escopo da rota.
• 400bad_requestCorpo malformado (JSON inválido). O status acompanha o motivo: 413 com corpo acima de 1 MB, 415 com Content-Type que não seja JSON — o código error continua bad_request.
• 500internalErro nosso.

Dispara uma ronda#

Enfileira uma ronda e responde 202 na hora com o id. A ronda não é instantânea (busca o app, roda dezenas de verificações e, com IA, ainda analisa), então o resultado você busca depois em GET /scans/{id} — ou recebe pelo webhook scan.completed.

Só target é obrigatório: sem mais nada, é a ronda padrão do painel (IA e infra ligadas, o resto desligado). As demais opções são as MESMAS da tela — testes autenticados, modo agressivo, LGPD e escopo extra de infra — com os mesmos padrões e as mesmas travas.

Cota, limite de apps, plano, verificação e autorização são decididos pelo MESMO caso de uso do painel: a chave muda quem chama, nunca o que é permitido. Ordem das travas: uso justo (429) → lista de bloqueio (403) → recurso do plano (403 feature_locked) → propriedade do app (403 domain_unverified) → confirmação intrusiva (400) → cota de IA (402) → limite de apps (402).

Corpo da requisição

JSON, com Content-Type: application/json.

Requisição

curl -X POST https://api.guarita.dev/v1/public/scans \
  -H "Authorization: Bearer $GUARITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "https://app.exemplo.com.br",
    "ai": true
  }'

{
  "id": "scan_e11a03d9",
  "status": "running"
}

Campos da resposta

Erros

• 400invalid_targettarget ausente ou não é URL completa (http:// ou https://).
• 400intrusive_unauthorizedaggressive: true sem authorized_intrusive: true. O modo agressivo mexe no app de verdade, e a confirmação é por ronda — a declaração da chave não basta.
• 402quota_exceededCota de análises com IA do mês esgotada (só com ai: true).
• 402domain_limitLimite de apps do plano atingido ao escanear um hostname NOVO.
• 403feature_lockedA ronda pediu um recurso que o plano da conta não inclui: authenticated ou aggressive (authenticatedScan) ou lgpd (lgpdScan).
• 403target_blockedAlvo na lista de bloqueio (órgão público, banco, grande plataforma) ou identificador interno de integração. Vale mesmo com a declaração de autorização da chave.
• 403domain_unverifiedai: true, authenticated: true ou aggressive: true num app sem prova de propriedade VIGENTE — nunca verificado, ou atestação de provedor vencida/revogada.
• 409domain_provider_conflictO hostname é de um projeto gerenciado por uma integração (Vercel ou Lovable).
• 429rate_limitedMuitas rondas em pouco tempo. O balde é por conta: 10 rondas de rajada, reabastecendo 1 por minuto.
• 401unauthorizedChave ausente, fora do formato Bearer gsk_…, inexistente, revogada — ou o plano da conta deixou de incluir a API. O corpo é o MESMO em todos os casos, de propósito. Vem com o header WWW-Authenticate.
• 403insufficient_scopeA chave é válida, mas não tem o escopo da rota.
• 400bad_requestCorpo malformado (JSON inválido). O status acompanha o motivo: 413 com corpo acima de 1 MB, 415 com Content-Type que não seja JSON — o código error continua bad_request.
• 500internalErro nosso.

Estado e resumo de uma ronda#

O endpoint de polling depois de POST /scans. Enquanto a ronda roda, progress diz onde ela está (fase, verificações feitas/previstas, verificação atual) e summary é null; quando status vira done, progress vira null e summary traz score, faixa e contagem de críticos.

Um id de outra conta responde 404, igual a um id inexistente — a API não confirma a existência de rondas de terceiros.

Parâmetros de rota

Requisição

curl https://api.guarita.dev/v1/public/scans/scan_7b3e9a12 \
  -H "Authorization: Bearer $GUARITA_API_KEY"

{
  "id": "scan_7b3e9a12",
  "hostname": "app.exemplo.com.br",
  "target": "https://app.exemplo.com.br",
  "status": "done",
  "created_at": "2026-08-27T14:02:56.902Z",
  "finished_at": "2026-08-27T14:09:24.106Z",
  "progress": null,
  "summary": {
    "id": "scan_7b3e9a12",
    "target": "https://app.exemplo.com.br",
    "hostname": "app.exemplo.com.br",
    "status": "done",
    "score": 78,
    "riskLabel": "HIGH_RISK",
    "criticalCount": 2,
    "finishedAt": "2026-08-27T14:09:24.106Z",
    "durationMs": 387096,
    "blocked": false
  }
}

Campos da resposta

Erros

• 404not_foundRonda inexistente, de outra conta, ou ainda sem relatório.
• 401unauthorizedChave ausente, fora do formato Bearer gsk_…, inexistente, revogada — ou o plano da conta deixou de incluir a API. O corpo é o MESMO em todos os casos, de propósito. Vem com o header WWW-Authenticate.
• 403insufficient_scopeA chave é válida, mas não tem o escopo da rota.
• 400bad_requestCorpo malformado (JSON inválido). O status acompanha o motivo: 413 com corpo acima de 1 MB, 415 com Content-Type que não seja JSON — o código error continua bad_request.
• 500internalErro nosso.

Cancela uma ronda em andamento#

Interrompe uma ronda que ainda está rodando (queued, running ou analyzing) e responde com o estado dela. É o botão "Cancelar" da tela de espera, pra quando o pipeline foi abortado ou a ronda saiu por engano.

Um id de outra conta responde 404, igual a um id inexistente.

Parâmetros de rota

Requisição

curl -X POST https://api.guarita.dev/v1/public/scans/scan_7b3e9a12/cancel \
  -H "Authorization: Bearer $GUARITA_API_KEY"

{
  "id": "scan_7b3e9a12",
  "status": "canceled",
  "finished_at": "2026-09-02T12:00:00.000Z"
}

Campos da resposta

Erros

• 404not_foundRonda inexistente, de outra conta, ou ainda sem relatório.
• 401unauthorizedChave ausente, fora do formato Bearer gsk_…, inexistente, revogada — ou o plano da conta deixou de incluir a API. O corpo é o MESMO em todos os casos, de propósito. Vem com o header WWW-Authenticate.
• 403insufficient_scopeA chave é válida, mas não tem o escopo da rota.
• 400bad_requestCorpo malformado (JSON inválido). O status acompanha o motivo: 413 com corpo acima de 1 MB, 415 com Content-Type que não seja JSON — o código error continua bad_request.
• 500internalErro nosso.