Referência da API

Acesse a Agent Breach de forma programática pela nossa API REST. Os limites de plano para targets, varreduras e achados são os mesmos do aplicativo web.

OpenAPI interativo

Esquemas ao vivo, exemplos de requisição e "Try it" (com suas credenciais). Swagger e ReDoc são servidos pelo backend da API, não pelo hub /docs deste site. Eles listam apenas a API pública de automação (targets, varreduras, achados, perfis de autenticação, agendamentos, CI, chaves de API, webhooks de saída, uso)—não toda a superfície do painel.

https://api.agentbreach.com/api/docs (Swagger UI; /docs no host da API redireciona para aqui quando roteado ao backend)
https://api.agentbreach.com/api/redoc (ReDoc)

Autenticação

Navegador / sessão: use o JWT do login como Authorization: Bearer <jwt>.
Automação (planos pagos): crie uma chave de API em Configurações → Segurança → Chaves de API. As chaves devem incluir o escopo api:access para endpoints REST. Envie o segredo como:

Authorization: Bearer ab_xxxxxxxx
# or
X-API-Key: ab_xxxxxxxx

Plano gratuito: não é possível criar nem usar chaves de API REST. Fluxos de CI / PR usam chaves separadas com o escopo ci:scan:write e apenas as rotas /ci-scans/....

Cabeçalho de workspace

Targets, varreduras e achados são escopados a um workspace (pessoal ou equipe), como no painel:

X-Org-Context: personal
# or your team workspace id from the app

URL base

https://agentbreach.com/api/v1

Seu app usa NEXT_PUBLIC_API_URL (por exemplo, a origem do site se as requisições forem proxyadas). Sobrescreva o host do Swagger/ReDoc com NEXT_PUBLIC_OPENAPI_ORIGIN quando forem diferentes (ex.: https://api.agentbreach.com).

Exemplos de requisição

Criar target

POST https://agentbreach.com/api/v1/targets

curl -sS -X POST "https://agentbreach.com/api/v1/targets" \
  -H "Authorization: Bearer ab_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Org-Context: personal" \
  -d '{
    "name": "Production API",
    "url": "https://api.example.com",
    "scope": {
      "include_paths": ["/v1"],
      "exclude_paths": ["/v1/admin"],
      "include_subdomains": false,
      "allow_reverse_ip_discovery": false,
      "ip_ranges": []
    },
    "cross_domain_consent": false
  }'

Criar varredura

POST https://agentbreach.com/api/v1/scans

curl -sS -X POST "https://agentbreach.com/api/v1/scans" \
  -H "Authorization: Bearer ab_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Org-Context: personal" \
  -d '{
    "target_id": "550e8400-e29b-41d4-a716-446655440000",
    "profile": "standard",
    "auth_profile_id": null,
    "selected_tools": null,
    "options": {}
  }'

Listar achados

GET https://agentbreach.com/api/v1/findings?limit=20&skip=0 — opcionais: target_id, scan_id, severity, status.

curl -sS "https://agentbreach.com/api/v1/findings?limit=10" \
  -H "Authorization: Bearer ab_YOUR_KEY" \
  -H "X-Org-Context: personal"

Atualizar achado

PATCH https://agentbreach.com/api/v1/findings/{id}

curl -sS -X PATCH "https://agentbreach.com/api/v1/findings/FINDING_ID" \
  -H "Authorization: Bearer ab_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Org-Context: personal" \
  -d '{"status": "accepted", "notes": "Risk accepted for this release."}'

Perfis de autenticação (opcional)

Crie perfis sob um target e passe auth_profile_id ao iniciar uma varredura.

curl -sS -X POST "https://agentbreach.com/api/v1/targets/TARGET_ID/auth-profiles" \
  -H "Authorization: Bearer ab_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Org-Context: personal" \
  -d '{
    "name": "Staging login",
    "type": "cookie",
    "config": {
      "cookie_name": "session",
      "login_url": "https://app.example.com/login"
    }
  }'

Visão geral dos endpoints

Targets

GET /targets — Listar targets
POST /targets — Criar target
GET /targets/:id — Obter target
PUT /targets/:id — Atualizar target
DELETE /targets/:id — Excluir target

Varreduras

GET /scans/available-tools — Catálogo de ferramentas
GET /scans — Listar varreduras
POST /scans — Criar e enfileirar varredura
GET /scans/:id — Obter varredura
POST /scans/:id/cancel — Cancelar
POST /scans/:id/retry — Tentar novamente

Achados

GET /findings — Listar achados (filtros: target_id, scan_id, severity, status)
GET /findings/:id — Obter achado
PATCH /findings/:id — Atualizar campos de triagem

Varreduras CI / PR

Requer chave de API com ci:scan:write (diferente de api:access).

POST /ci-scans/start — Enfileirar varredura de PR
POST /ci-scans/:id/results — Enviar resultados

Erros

Corpos de erro JSON normalmente usam o campo detail (string ou objeto aninhado para validação):

{ "detail": "Could not validate credentials" }
{ "detail": "Missing required API key scope: api:access" }
{ "detail": [ { "loc": ["body", "url"], "msg": "field required", "type": "value_error.missing" } ] }

Limites de taxa

Limites horários por plano aplicam-se a requisições mutantes; veja os cabeçalhos X-RateLimit-* quando aplicável. Limites aproximados por plano:

Gratuito: 100 requisições por hora
Startup: 1.000 requisições por hora
Pro: 10.000 requisições por hora
Enterprise: 100.000 requisições por hora

Algumas rotas têm limites mais rígidos por caminho (ex.: criação de varredura). Tráfego não autenticado pode ser identificado por IP.

Mais ajuda

Consulte o hub de documentação, os links OpenAPI acima ou fale com o suporte.