Referência para desenvolvedores

Referência da API

Crie um fluxo completo de segurança ofensiva: registre um target, inicie e monitore varreduras, obtenha evidências, exporte relatórios e verifique correções.

Testar a API Criar chave de API

Conecte-se com segurança

Crie uma chave de plano pago com api:access, armazene-a como secret mascarado do CI e envie-a em todas as requisições. Operações de alteração exigem papel de editor ou owner no workspace selecionado.

Autenticação

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:

Cabeçalho da requisição

X-API-Key: ab_YOUR_KEY
# Alternativa: Authorization: Bearer ab_YOUR_KEY

Plano gratuito: não é possível criar nem usar chaves de API REST. A ingestão de resultados de CI / PR usa o escopo ci:scan:write e as rotas /ci-scans/.... Uma chave pode incluir ci:scan:write e api:access.

Cabeçalho de workspace

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

Cabeçalho da requisição

X-Org-Context: personal
# ou o domínio normalizado da organização da equipe, por exemplo example.com

URL base

https://agentbreach.com/api/v1

Acrescente a esta URL os caminhos dos endpoints abaixo. A referência usa automaticamente a origem atual da API Agent Breach.

OpenAPI interativo

Use o Swagger para testar rotas públicas e o ReDoc para consultar seus esquemas. Este guia acrescenta o comportamento de fluxos, relatórios e recuperação que um esquema isolado não explica.

Swagger UI ReDoc

Do target ao resultado verificado

O fluxo normal de automação tem cinco etapas. Cada cartão leva a uma requisição completa e a uma resposta representativa.

1
Registre o target
Defina os caminhos autorizados e salve o id retornado do target.
2
Enfileire a varredura
Escolha um perfil e salve o novo id da varredura antes de continuar.
3
Aguarde um estado terminal
Consulte a varredura com timeout até ela concluir, falhar ou ser cancelada.
4
Consuma as evidências
Percorra os achados, confira a confirmação e depois exporte o relatório.
5
Exporte o relatório
Baixe um resultado processável com qualidade da execução, evidência, cobertura e mapeamentos de frameworks.

Campos importantes para automação

Estes campos evitam que o pipeline trate atividade, candidatos ou observações consultivas como impacto de segurança confirmado.

Estado e cobertura da varredura

Use status para controlar as consultas. progress e completed_summary_eligible não garantem cobertura; consulte run_assessment e seus códigos de motivo.

Critério de vulnerabilidade confirmada

Use report_assessment.validation_confirmed == true como critério. Severidade, contadores e included_in_current_report isoladamente são inseguros porque candidatos e recomendações de hardening também podem ser armazenados.

Evidência e reprodução

O detalhe do achado expõe reproduction_steps, proof_of_concept e evidence_documentation. reproducibility: not_assessed descreve evidência registrada sem afirmar que houve reprodução independente.

Paginação

Achados retornam items, total, skip e limit. O limite máximo é 100; continue até ler todos os itens indicados em total.

Requisições e respostas

Os exemplos usam ids fictícios e uma chave mascarada. As respostas mostram os campos úteis para a próxima etapa; consulte o OpenAPI para todos os campos opcionais.

POST/targets

Criar um target autorizado

Defina a URL e o limite da varredura. Aceite o consentimento entre domínios somente quando houver autorização para um target fora do domínio da conta.

Requisição

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

Resposta201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production API",
  "url": "https://api.example.com/",
  "target_domain": "api.example.com",
  "scope": {
    "include_hosts": [
      "api.example.com"
    ],
    "include_paths": [
      "/v1"
    ],
    "exclude_paths": [
      "/v1/admin"
    ],
    "include_subdomains": false
  },
  "cross_domain_consent_accepted": true,
  "status": "active",
  "created_at": "2026-09-11T16:00:00Z",
  "updated_at": "2026-09-11T16:00:00Z"
}

Salve id como o target id usado na criação da varredura. A API valida acesso, escopo, capacidade do plano e consentimento entre domínios.

POST/scans

Criar e enfileirar uma varredura

Os perfis integrados são quick, standard e deep. Adicione auth_profile_ids ativos quando a avaliação exigir cobertura autenticada.

Requisição

curl -fsS -X POST "https://agentbreach.com/api/v1/scans" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal" \
  -H "Content-Type: application/json" \
  --data '{
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "profile": "standard",
  "auth_profile_ids": [],
  "options": {}
}'

Resposta201 Created

{
  "id": "7a243f5d-d539-40d7-986c-0f460adc79a6",
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "profile": "standard",
  "status": "queued",
  "progress": 0,
  "findings_count": 0,
  "critical_count": 0,
  "high_count": 0,
  "created_at": "2026-09-11T16:01:00Z",
  "run_assessment": {
    "contract_version": 1,
    "status": "queued",
    "recorded_status": "queued",
    "completion_recorded": false,
    "execution_detail_status": "not_loaded",
    "completed_summary_eligible": false,
    "coverage_assurance": "not_assessed",
    "freshness": "unknown",
    "reason_codes": [
      "run_not_completed",
      "execution_details_not_loaded",
      "activity_not_recorded"
    ]
  }
}

POST /scans não possui chave de idempotência. Salve o scan id retornado e não repita uma criação incerta automaticamente, pois isso pode enfileirar uma varredura duplicada.

GET/scans/{scan_id}

Monitorar o estado da varredura

Repita esta consulta de status com espera limitada. Estados ativos: queued, running e paused; estados terminais: completed, failed e cancelled.

Requisição

curl -fsS "https://agentbreach.com/api/v1/scans/7a243f5d-d539-40d7-986c-0f460adc79a6" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal"

Resposta200 OK

{
  "id": "7a243f5d-d539-40d7-986c-0f460adc79a6",
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "progress": 100,
  "display_progress": 100,
  "findings_count": 3,
  "critical_count": 0,
  "high_count": 1,
  "medium_count": 1,
  "low_count": 0,
  "info_count": 1,
  "current_tool": null,
  "completed_at": "2026-09-11T16:22:14Z",
  "run_assessment": {
    "contract_version": 1,
    "status": "completed",
    "recorded_status": "completed",
    "completion_recorded": true,
    "execution_detail_status": "not_loaded",
    "failed_execution_count": null,
    "incomplete_execution_count": null,
    "unclassified_execution_count": null,
    "completed_summary_eligible": null,
    "coverage_assurance": "not_assessed",
    "freshness": "historical",
    "last_activity_at": "2026-09-11T16:22:14Z",
    "evaluated_at": "2026-09-11T16:25:00Z",
    "reason_codes": [
      "execution_details_not_loaded"
    ]
  }
}

Completed registra o fim do ciclo. Consulte run_assessment para ver atualização e ressalvas de execução; progress 100 sozinho não comprova cobertura.

GET/findings?scan_id={scan_id}&severity=critical,high&limit=100&skip=0

Listar e filtrar achados

Esta requisição busca uma página. Filtre por varredura, target, severidade, status, host ou classificação e avance skip até baixar todos os itens de total.

Requisição

curl -fsS "https://agentbreach.com/api/v1/findings?scan_id=7a243f5d-d539-40d7-986c-0f460adc79a6&severity=critical,high&limit=100&skip=0" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal"

Resposta200 OK

{
  "items": [
    {
      "id": "6ed1e606-0ed8-4528-bd7d-3df0cbe9b97c",
      "scan_id": "7a243f5d-d539-40d7-986c-0f460adc79a6",
      "target_id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "SQL injection in order search",
      "severity": "high",
      "status": "confirmed",
      "type": "sql_injection",
      "source_tool": "nuclei",
      "confidence": "high",
      "validation_status": "confirmed",
      "url": "https://api.example.com/v1/orders?query=test",
      "method": "GET",
      "parameter": "query",
      "report_assessment": {
        "record_kind": "finding",
        "included_in_current_report": true,
        "validation_confirmed": true,
        "route_existence": null
      }
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 100
}

Use report_assessment.validation_confirmed como critério de vulnerabilidade. Um filtro de scan inexistente atualmente retorna página vazia em vez de 404.

GET/findings/{finding_id}

Obter evidência e PoC registrados

A resposta detalhada contém passos registrados, prova de conceito, resultado observado, correção, validação e classificação do relatório.

Requisição

curl -fsS "https://agentbreach.com/api/v1/findings/6ed1e606-0ed8-4528-bd7d-3df0cbe9b97c" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal"

Resposta200 OK

{
  "id": "6ed1e606-0ed8-4528-bd7d-3df0cbe9b97c",
  "scan_id": "7a243f5d-d539-40d7-986c-0f460adc79a6",
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "SQL injection in order search",
  "severity": "high",
  "status": "confirmed",
  "type": "sql_injection",
  "source_tool": "nuclei",
  "description": "The query parameter changed the database response during validation.",
  "reproduction_steps": [
    "Send the recorded GET request to /v1/orders with the saved query value.",
    "Replay the same request with the recorded validation value.",
    "Compare the response status, body signature, and elapsed time."
  ],
  "proof_of_concept": {
    "method": "GET",
    "url": "https://api.example.com/v1/orders",
    "parameter": "query",
    "payload": "test' OR '1'='1",
    "request": "GET /v1/orders?query={{RECORDED_TEST_VALUE}} HTTP/1.1",
    "observed_result": "The response changed consistently across the validation controls.",
    "observed_at": "2026-09-11T16:18:02Z"
  },
  "validation_actions": [
    {
      "action": "control_comparison",
      "evidence": "The recorded payload and false-condition control produced different response signatures."
    }
  ],
  "remediation": "Use a parameterized query and validate the query input server-side.",
  "url": "https://api.example.com/v1/orders?query=test",
  "method": "GET",
  "parameter": "query",
  "discovered_at": "2026-09-11T16:18:02Z",
  "evidence_documentation": {
    "recorded_step_count": 3,
    "supporting_material_present": true,
    "observed_result_present": true,
    "validation_notes_present": true,
    "missing_fields": [],
    "reproducibility": "not_assessed"
  },
  "report_assessment": {
    "record_kind": "finding",
    "included_in_current_report": true,
    "validation_confirmed": true,
    "route_existence": null
  }
}

Valores sensíveis podem ser ocultados. A documentação da evidência informa o que existe ou falta e não certifica a reprodução de forma independente.

PATCH/findings/{finding_id}

Atualizar a triagem

Defina status, notas e responsável. Os estados suportados são new, confirmed, false_positive, accepted_risk e fixed.

Requisição

curl -fsS -X PATCH "https://agentbreach.com/api/v1/findings/6ed1e606-0ed8-4528-bd7d-3df0cbe9b97c" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal" \
  -H "Content-Type: application/json" \
  --data '{
  "status": "accepted_risk",
  "notes": "Accepted for release 2026.09; compensating control documented in SEC-184.",
  "assigned_to": "security@example.com"
}'

Resposta200 OK

{
  "id": "6ed1e606-0ed8-4528-bd7d-3df0cbe9b97c",
  "status": "accepted_risk",
  "assigned_to": "security@example.com",
  "notes": "Accepted for release 2026.09; compensating control documented in SEC-184.",
  "report_assessment": {
    "record_kind": "finding",
    "included_in_current_report": false,
    "validation_confirmed": false,
    "route_existence": null
  }
}

Riscos aceitos, falsos positivos e itens corrigidos ficam fora dos relatórios de vulnerabilidades ativas. Definir fixed registra a data da correção.

GET/reports/scans/{scan_id}?format=json

Baixar o relatório processável

O JSON contém avaliação da execução, achados filtrados por evidência, resumo dos testes, cobertura de URLs e mapeamentos de frameworks.

Requisição

curl -fsS "https://agentbreach.com/api/v1/reports/scans/7a243f5d-d539-40d7-986c-0f460adc79a6?format=json" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal"

Resposta200 OK

{
  "report_type": "security_scan",
  "run_assessment": {
    "contract_version": 1,
    "status": "completed",
    "recorded_status": "completed",
    "completion_recorded": true,
    "execution_detail_status": "available",
    "failed_execution_count": 0,
    "incomplete_execution_count": 0,
    "unclassified_execution_count": 0,
    "completed_summary_eligible": true,
    "coverage_assurance": "not_assessed",
    "freshness": "historical",
    "last_activity_at": "2026-09-11T16:22:14Z",
    "evaluated_at": "2026-09-11T16:25:00Z",
    "reason_codes": []
  },
  "run_assessment_notice": "Run state: Completion recorded. Completion was recorded. The saved results do not establish complete coverage or that the target is secure. Last recorded run activity: 2026-09-11T16:22:14+00:00.",
  "executive_summary": {
    "scan_id": "7a243f5d-d539-40d7-986c-0f460adc79a6",
    "total_findings": 1,
    "material_findings": 1,
    "validation_confirmed": 1,
    "informational_hardening": 0,
    "severity_breakdown": {
      "critical": 0,
      "high": 1,
      "medium": 0,
      "low": 0,
      "info": 0
    },
    "risk_score_basis": "confirmed_vulnerabilities_only"
  },
  "findings": [
    {
      "id": "6ed1e606-0ed8-4528-bd7d-3df0cbe9b97c",
      "severity": "high",
      "validation_status": "confirmed"
    }
  ],
  "test_execution_summary": {
    "total_tests": 18,
    "successful_tests": 18,
    "failed_tests": 0,
    "total_duration_seconds": 1284,
    "tools_used": [
      "nuclei",
      "browser_agent"
    ]
  },
  "urls_tested": [
    {
      "url": "https://shop.example.com/",
      "authenticated": false
    },
    {
      "url": "https://shop.example.com/account",
      "authenticated": true
    }
  ],
  "total_urls_tested": 18,
  "framework_mappings": {
    "owasp_top_10": [
      "A03:2021 Injection"
    ],
    "cwe": [
      "CWE-89"
    ]
  },
  "generated_at": "2026-09-11T16:25:00Z"
}

Filtre por severidade e idioma; o JSON também aceita include_frameworks. Há CSV, Markdown, Jira, PDF e evidence-pack. Use template=developer para PDF síncrono; o PDF de IA padrão pode retornar 202 e ser entregue por e-mail.

POST/scans/{scan_id}/verification-rerun

Verificar novamente achados abertos

Enfileire uma verificação no mesmo scan e conjunto de achados depois do trabalho de correção.

Requisição

curl -fsS -X POST "https://agentbreach.com/api/v1/scans/7a243f5d-d539-40d7-986c-0f460adc79a6/verification-rerun" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal"

Resposta200 OK

{
  "id": "7a243f5d-d539-40d7-986c-0f460adc79a6",
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "progress": 0,
  "execution_phase": "verification_rerun",
  "findings_count": 3,
  "options": {
    "verification_rerun": {
      "tools": [
        "nuclei"
      ],
      "finding_ids": [
        "6ed1e606-0ed8-4528-bd7d-3df0cbe9b97c"
      ],
      "requested_at": "2026-09-11T16:30:00Z",
      "previous_status": "completed",
      "parent_scan_id": "7a243f5d-d539-40d7-986c-0f460adc79a6"
    }
  },
  "run_assessment": {
    "contract_version": 1,
    "status": "queued",
    "recorded_status": "queued",
    "completion_recorded": false,
    "execution_detail_status": "not_loaded",
    "completed_summary_eligible": false,
    "coverage_assurance": "not_assessed",
    "freshness": "unknown",
    "reason_codes": [
      "run_not_completed",
      "execution_details_not_loaded"
    ]
  }
}

Não consome cota de nova varredura nem cria achados. Achados redescobertos continuam vulneráveis; ausência em ferramenta ampla permanece inconclusiva.

Ingestão de resultados de CI / PR

Estes endpoints acompanham um check de pull request e recebem resultados produzidos pelas ferramentas do seu CI. Eles não iniciam uma varredura DAST web ou API.

Abrir o guia completo de integração CI/CD

POST/ci-scans/start

Criar o registro de acompanhamento do CI

Crie um registro para o repositório, pull request, commit e execução do workflow antes de enviar os resultados. Esta rota exige ci:scan:write.

Requisição

curl -fsS -X POST "https://agentbreach.com/api/v1/ci-scans/start" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal" \
  -H "Content-Type: application/json" \
  --data '{
  "provider": "github",
  "repository": "acme/storefront",
  "pr_number": 184,
  "base_sha": "68f070f",
  "head_sha": "0d5a8ee",
  "branch": "fix/order-search",
  "workflow_run_id": "9876543210",
  "options": {}
}'

Resposta201 Created

{
  "id": "7c3d2f48-76a7-4df8-9b17-90bd8b175bf8",
  "user_id": "9be5688a-f23b-46d1-94b4-6a9d8682492e",
  "provider": "github",
  "repository": "acme/storefront",
  "pr_number": 184,
  "base_sha": "68f070f",
  "head_sha": "0d5a8ee",
  "branch": "fix/order-search",
  "workflow_run_id": "9876543210",
  "status": "queued",
  "policy_result": null,
  "findings_count": 0,
  "critical_count": 0,
  "high_count": 0,
  "medium_count": 0,
  "low_count": 0,
  "info_count": 0,
  "options": {},
  "results_summary": null,
  "error_message": null,
  "created_at": "2026-09-11T16:40:00Z",
  "started_at": null,
  "completed_at": null
}

Salve o id retornado. Este é um registro de ingestão/check; use POST /scans para varredura web ou API da Agent Breach.

POST/ci-scans/{ci_scan_id}/results

Enviar achados do CI

Envie achados de código normalizados e a decisão de política do pipeline ao registro de CI existente.

Requisição

curl -fsS -X POST "https://agentbreach.com/api/v1/ci-scans/7c3d2f48-76a7-4df8-9b17-90bd8b175bf8/results" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal" \
  -H "Content-Type: application/json" \
  --data '{
  "findings": [
    {
      "title": "Hardcoded deployment token",
      "severity": "high",
      "type": "secret_exposure",
      "description": "A live deployment token is committed in a workflow file.",
      "file_path": ".github/workflows/deploy.yml",
      "line": 24,
      "rule_id": "secrets/live-token",
      "source_tool": "gitleaks",
      "evidence": "Token fingerprint ending in 4f2c"
    }
  ],
  "policy_result": "fail",
  "summary": {
    "files_scanned": 312,
    "rules_run": 48
  }
}'

Resposta200 OK

{
  "id": "7c3d2f48-76a7-4df8-9b17-90bd8b175bf8",
  "repository": "acme/storefront",
  "pr_number": 184,
  "status": "running",
  "policy_result": null,
  "findings_count": 0,
  "high_count": 0,
  "results_summary": null,
  "started_at": "2026-09-11T16:41:00Z",
  "completed_at": null
}

A resposta imediata pode continuar running enquanto o processamento assíncrono atualiza contadores e policy_result. Consulte GET /ci-scans/{ci_scan_id} para o registro final.

Escolha a ação correta de reprocessamento

Estas operações mantêm o mesmo engagement, mas resolvem problemas diferentes. Não recebem corpo e retornam o scan ou achado atualizado.

POST/scans/{scan_id}/retry

Tentar novamente uma varredura interrompida

Use para scans enfileirados, falhos, pausados ou comprovadamente travados. Checkpoints recuperáveis são preservados.

Mostrar requisição e resposta

Requisição

curl -fsS -X POST "https://agentbreach.com/api/v1/scans/7a243f5d-d539-40d7-986c-0f460adc79a6/retry" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal"

Resposta200 OK

{
  "id": "7a243f5d-d539-40d7-986c-0f460adc79a6",
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "progress": 0,
  "resume_count": 1,
  "worker_id": null,
  "completed_at": null
}

Uma varredura saudável em execução e outros estados terminais retornam 400. A resposta é a mesma varredura enfileirada novamente; resume_count aumenta.

POST/scans/{scan_id}/resume

Retomar a partir dos checkpoints

Recupera a orquestração usando checkpoints e artefatos salvos. Um target pausado precisa estar acessível.

Mostrar requisição e resposta

Requisição

curl -fsS -X POST "https://agentbreach.com/api/v1/scans/7a243f5d-d539-40d7-986c-0f460adc79a6/resume" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal"

Resposta200 OK

{
  "id": "7a243f5d-d539-40d7-986c-0f460adc79a6",
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "progress": 62,
  "resume_count": 2,
  "worker_id": null,
  "execution_phase": null
}

A resposta preserva o progresso existente e enfileira a orquestração. Um target pausado e inacessível ou um estado incompatível retorna 400.

POST/scans/{scan_id}/verification-rerun

Verificar novamente achados abertos

Usa o mesmo scan e os ids existentes sem consumir nova cota. Ausência em uma ferramenta ampla permanece inconclusiva.

Mostrar requisição e resposta

Requisição

curl -fsS -X POST "https://agentbreach.com/api/v1/scans/7a243f5d-d539-40d7-986c-0f460adc79a6/verification-rerun" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal"

Resposta200 OK

{
  "id": "7a243f5d-d539-40d7-986c-0f460adc79a6",
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "progress": 0,
  "execution_phase": "verification_rerun",
  "options": {
    "verification_rerun": {
      "tools": [
        "nuclei"
      ],
      "finding_ids": [
        "6ed1e606-0ed8-4528-bd7d-3df0cbe9b97c"
      ],
      "requested_at": "2026-09-11T16:30:00Z",
      "previous_status": "completed",
      "parent_scan_id": "7a243f5d-d539-40d7-986c-0f460adc79a6"
    }
  }
}

Exige uma varredura completed ou failed com achados abertos elegíveis. Caso contrário, a API retorna 400 em vez de iniciar uma verificação vazia.

POST/scans/{scan_id}/tools/{tool_name}/rerun

Executar novamente um scanner

Substitui a saída retida da ferramenta e concilia os resultados observados no mesmo scan.

Mostrar requisição e resposta

Requisição

curl -fsS -X POST "https://agentbreach.com/api/v1/scans/7a243f5d-d539-40d7-986c-0f460adc79a6/tools/nuclei/rerun" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal"

Resposta200 OK

{
  "id": "7a243f5d-d539-40d7-986c-0f460adc79a6",
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "completed_at": null,
  "options": {
    "tool_rerun": {
      "tool": "nuclei",
      "requested_at": "2026-09-11T16:32:00Z",
      "previous_status": "completed"
    }
  }
}

Use um id canônico de ferramenta obtido em GET /scans/available-tools. Ferramenta desconhecida ou estado incompatível retorna 400.

POST/scans/{scan_id}/rehydrate-findings

Recuperar achados armazenados

Reconstrói os achados no banco a partir dos artefatos retidos. Não envia novo tráfego ao target.

Mostrar requisição e resposta

Requisição

curl -fsS -X POST "https://agentbreach.com/api/v1/scans/7a243f5d-d539-40d7-986c-0f460adc79a6/rehydrate-findings" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal"

Resposta200 OK

{
  "id": "7a243f5d-d539-40d7-986c-0f460adc79a6",
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "progress": 100,
  "findings_count": 3,
  "critical_count": 0,
  "high_count": 1,
  "medium_count": 1,
  "low_count": 0,
  "info_count": 1
}

Use somente quando houver saída retida. Se os artefatos não contiverem achados, a API retorna 400 e mantém a varredura inalterada.

POST/findings/{finding_id}/verify-fix

Reproduzir um PoC

Enfileira no worker a reprodução dentro do escopo das trocas de controle e prova registradas para um achado de erro SQL diferencial.

Mostrar requisição e resposta

Requisição

curl -fsS -X POST "https://agentbreach.com/api/v1/findings/6ed1e606-0ed8-4528-bd7d-3df0cbe9b97c/verify-fix" \
  -H "X-API-Key: ab_YOUR_KEY" \
  -H "X-Org-Context: personal"

Resposta200 OK

{
  "id": "6ed1e606-0ed8-4528-bd7d-3df0cbe9b97c",
  "scan_id": "7a243f5d-d539-40d7-986c-0f460adc79a6",
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "confirmed",
  "fix_verification_status": "still_vulnerable",
  "fix_verified_at": "2026-09-11T16:35:00Z",
  "report_assessment": {
    "record_kind": "finding",
    "included_in_current_report": true,
    "validation_confirmed": true,
    "route_existence": null
  }
}

A resposta inicial é pending; consulte GET /findings/{finding_id}. Uma correção verificada muda o achado para fixed. Evidência ausente, alvo inacessível e classes não suportadas permanecem inconclusive.

Endpoints comuns

Este catálogo compacto cobre o principal fluxo de automação. Use Swagger ou ReDoc acima para perfis de autenticação, agendamentos, chaves de API, webhooks, uso, eventos ao vivo, saídas de ferramentas e esquemas das rotas públicas.

Targets

GET /targetsListar targets
POST /targetsCriar target
GET /targets/{target_id}Obter target
PATCH /targets/{target_id}Atualizar target
DELETE /targets/{target_id}Excluir de forma lógica um target nunca escaneado ou inativo por seis meses

Varreduras

GET /scans/available-toolsCatálogo de ferramentas
GET /scansListar varreduras
POST /scansCriar e enfileirar varredura
GET /scans/{scan_id}Obter estado e avaliação da varredura
POST /scans/{scan_id}/cancelCancelar uma varredura ativa
POST /scans/{scan_id}/retryRecuperar varredura enfileirada, falha, pausada ou travada
POST /scans/{scan_id}/verification-rerunVerificar novamente achados abertos
POST /scans/{scan_id}/tools/{tool_name}/rerunExecutar novamente uma ferramenta
POST /scans/{scan_id}/resumeRetomar checkpoints e artefatos salvos
POST /scans/{scan_id}/rehydrate-findingsReconstruir achados a partir das saídas retidas

Achados

GET /findingsListar achados (filtros: target_id, scan_id, severity, status)
GET /findings/{finding_id}Obter detalhes de evidência e reprodução
GET /findings/{finding_id}/tool-outputObter saída retida da ferramenta de origem (404 se ausente ou expirada)
PATCH /findings/{finding_id}Atualizar campos de triagem
POST /findings/{finding_id}/verify-fixReproduzir um PoC concreto

Relatórios

GET /reports/scans/{scan_id}Exportar JSON, CSV, PDF, Markdown, Jira ou evidence pack
GET /reports/targets/{target_id}Consolidar achados ativos; a varredura mais recente ancora os metadados

Varreduras CI / PR

Estas rotas recebem resultados de PR/código e exigem ci:scan:write. POST /ci-scans/start cria um registro de acompanhamento; ele não inicia DAST web/API. Uma chave pode incluir os escopos de CI e REST.

POST /ci-scans/startCriar um registro de PR/check para ingestão de resultados
POST /ci-scans/{ci_scan_id}/resultsEnviar resultados
GET /ci-scans/{ci_scan_id}Consultar o resultado do processamento

Erros

Erros usam o campo detail. Ele pode ser uma string, um erro estruturado de consentimento ou uma lista de problemas de validação.

Autenticação inválida401

{
  "detail": "Could not validate credentials"
}

Escopo ou papel ausente403

{
  "detail": "Missing required API key scope: api:access"
}

Corpo da requisição inválido422

{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "body",
        "url"
      ],
      "msg": "Field required"
    }
  ]
}

400

Filtros, transição de estado, escopo, consentimento ou semântica da requisição inválidos.

401

Credenciais ausentes, expiradas, revogadas ou inválidas.

403

Identidade válida sem plano, escopo, papel no workspace ou direito necessário.

404

O target, scan, achado, registro de CI ou saída retida não existe neste workspace.

429

Limite de alterações excedido. Leia Retry-After e os cabeçalhos X-RateLimit antes de tentar novamente.

Limites de taxa

Requisições que alteram dados podem retornar 429 com os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e Retry-After.

Trate os cabeçalhos da resposta como referência e use espera limitada. A criação de varreduras pode ter limites mais rígidos do que outras alterações.

Retry-After: 3600

Mais ajuda

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

Referência da API

Conecte-se com segurança

Autenticação

Cabeçalho de workspace

URL base

OpenAPI interativo

Do target ao resultado verificado

Registre o target

Enfileire a varredura

Aguarde um estado terminal

Consuma as evidências

Exporte o relatório

Campos importantes para automação

Estado e cobertura da varredura

Critério de vulnerabilidade confirmada

Evidência e reprodução

Paginação

Requisições e respostas

Ingestão de resultados de CI / PR

Escolha a ação correta de reprocessamento

Tentar novamente uma varredura interrompida

Retomar a partir dos checkpoints

Verificar novamente achados abertos

Executar novamente um scanner

Recuperar achados armazenados

Reproduzir um PoC

Endpoints comuns

Erros

Limites de taxa

Mais ajuda