Referencia para desarrolladores

Referencia de la API

Construye un flujo completo de seguridad ofensiva: registra un objetivo, lanza y supervisa escaneos, obtén evidencias, exporta informes y vuelve a comprobar las correcciones.

Probar la API Crear clave de API

Conéctate de forma segura

Crea una clave de un plan de pago con api:access, guárdala como secreto enmascarado en el CI y envíala en cada petición. Las operaciones que modifican datos requieren el rol de editor o propietario en el espacio de trabajo seleccionado.

Autenticación

Automatización (planes de pago): crea una clave de API en Configuración → Seguridad → Claves de API. Las claves deben incluir el ámbito api:access para los endpoints REST. Envía el secreto de una de estas formas:

Cabecera de la petición

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

Plan gratuito: no puedes crear ni usar claves de la API REST. La ingesta de resultados de CI / PR usa el ámbito ci:scan:write y las rutas /ci-scans/.... Una misma clave de API puede incluir ci:scan:write y api:access.

Cabecera del espacio de trabajo

Los objetivos, escaneos, hallazgos e informes se limitan a un espacio de trabajo (personal o de equipo), igual que en el panel:

Cabecera de la petición

X-Org-Context: personal
# o el dominio normalizado de la organización del equipo, por ejemplo example.com

URL base

https://agentbreach.com/api/v1

Añade a esta URL las rutas de los endpoints de abajo. La referencia usa automáticamente el origen actual de la API de Agent Breach.

OpenAPI interactivo

Usa Swagger para probar las rutas públicas y ReDoc para consultar sus esquemas. Esta guía añade el comportamiento de flujos, informes y recuperación que un esquema por sí solo no puede explicar.

Swagger UI ReDoc

Del objetivo al resultado verificado

El flujo de automatización habitual tiene cinco pasos. Cada tarjeta enlaza a una petición completa y una respuesta representativa.

1
Registra el objetivo
Define las rutas autorizadas y guarda el id del objetivo devuelto.
2
Encola un escaneo
Elige un perfil y guarda el id del nuevo escaneo antes de hacer nada más.
3
Espera a un estado final
Consulta el registro del escaneo con un tiempo máximo hasta que se complete, falle o se cancele.
4
Consume las evidencias
Pagina los hallazgos, revisa los metadatos de confirmación y exporta el informe.
5
Exporta el informe
Descarga un resultado legible por máquina con la calidad de la ejecución, las evidencias, la cobertura y el mapeo a marcos.

Campos que importan en la automatización

Estos campos evitan que un pipeline trate la actividad, los candidatos o las observaciones informativas como un impacto de seguridad confirmado.

Estado y cobertura del escaneo

Usa status para controlar las consultas. progress y completed_summary_eligible no garantizan la cobertura; revisa run_assessment y sus códigos de motivo.

Control de vulnerabilidades confirmadas

Aplica el control con report_assessment.validation_confirmed == true. La severidad, los contadores del escaneo e included_in_current_report por sí solos no son seguros, porque también pueden guardarse candidatos y recomendaciones de bastionado.

Evidencias y reproducibilidad

El detalle del hallazgo expone reproduction_steps, proof_of_concept y evidence_documentation. reproducibility: not_assessed significa que la API describe las evidencias registradas sin afirmar que se hayan reproducido de forma independiente.

Paginación

Los hallazgos devuelven items, total, skip y limit. El límite máximo es 100, así que continúa hasta haber leído todos los elementos de total.

Peticiones y respuestas

Los ejemplos usan ids de ejemplo y una clave de API enmascarada. Las respuestas muestran los campos más útiles para el siguiente paso del pipeline; consulta OpenAPI para ver todos los campos opcionales.

POST/targets

Crea un objetivo autorizado

Define la URL y los límites del escaneo. Activa el consentimiento entre dominios solo cuando tengas autorización para escanear un objetivo fuera del dominio de la cuenta.

Petición

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
}'

Respuesta201 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"
}

Guarda id como id del objetivo para crear el escaneo. La API valida la accesibilidad y puede rechazar un alcance no válido, la falta de capacidad del plan o la ausencia de consentimiento entre dominios.

POST/scans

Crea y encola un escaneo

Los perfiles integrados son quick, standard y deep. Añade auth_profile_ids activos cuando la evaluación necesite cobertura autenticada.

Petición

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": {}
}'

Respuesta201 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 no tiene clave de idempotencia. Guarda el id del escaneo devuelto y nunca repitas a ciegas una petición de creación dudosa, porque podrías encolar un escaneo duplicado.

GET/scans/{scan_id}

Supervisa el estado del escaneo

Repite esta única petición de estado con una espera acotada. Los estados activos son queued, running y paused; los estados finales guardados son completed, failed y cancelled.

Petición

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"

Respuesta200 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"
    ]
  }
}

El estado completed registra el fin del ciclo de vida. Lee run_assessment para conocer la actualidad y las salvedades de la ejecución; progress 100 por sí solo no demuestra la cobertura.

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

Lista y filtra hallazgos

Esta petición obtiene una página. Filtra por escaneo, objetivo, severidad, estado, host o clasificación y avanza skip hasta descargar todos los elementos de total.

Petición

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"

Respuesta200 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
}

Usa report_assessment.validation_confirmed para los controles de vulnerabilidades. Un filtro por un escaneo inexistente devuelve actualmente una página vacía en lugar de un 404.

GET/findings/{finding_id}

Obtén las evidencias registradas y la PoC

La respuesta de detalle contiene los pasos registrados, la prueba de concepto, el resultado observado, la corrección, la validación y la clasificación en el informe de un hallazgo.

Petición

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"

Respuesta200 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
  }
}

Los valores sensibles pueden estar ocultos. La documentación de evidencias indica lo que está presente o falta y no certifica por sí misma la reproducibilidad.

PATCH/findings/{finding_id}

Actualiza el estado de clasificación

Define el estado, las notas y la asignación. Los estados admitidos son new, confirmed, false_positive, accepted_risk y fixed.

Petición

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"
}'

Respuesta200 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
  }
}

Los registros con riesgo aceptado, falso positivo y corregido se excluyen de los informes de vulnerabilidades activas. Marcar fixed registra la fecha de corrección.

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

Descarga el informe legible por máquina

El JSON contiene la evaluación de la ejecución, los hallazgos filtrados por evidencias, el resumen de ejecución, la cobertura de URLs y el mapeo a marcos.

Petición

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"

Respuesta200 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"
}

Filtra por severidad y locale; el JSON también acepta include_frameworks. Hay disponibles CSV, Markdown, Jira, PDF y paquete de evidencias. Usa template=developer para un PDF síncrono; el PDF con IA predeterminado puede devolver 202 y enviarse por correo.

POST/scans/{scan_id}/verification-rerun

Vuelve a comprobar los hallazgos abiertos

Encola una pasada de verificación sobre el mismo escaneo y el mismo conjunto de hallazgos después de corregir.

Petición

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"

Respuesta200 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"
    ]
  }
}

No consume cupo de escaneos ni crea hallazgos nuevos. Los hallazgos que se vuelven a detectar siguen siendo vulnerables; si una herramienta general no los detecta, el resultado queda como no concluyente.

Ingesta de resultados de CI / PR

Estos endpoints registran una comprobación de pull request y aceptan los resultados que generan tus herramientas de CI. No lanzan un escaneo DAST de web o API.

Abrir la guía completa de integración con CI/CD

POST/ci-scans/start

Crea el registro de seguimiento de CI

Crea un registro para el repositorio, el pull request, el commit y la ejecución del workflow antes de subir los resultados de los escáneres. Esta ruta requiere ci:scan:write.

Petición

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": {}
}'

Respuesta201 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
}

Guarda el id devuelto. Es un registro del ciclo de ingesta/comprobación; usa POST /scans para el escaneo web o de API de Agent Breach.

POST/ci-scans/{ci_scan_id}/results

Envía los hallazgos de CI

Sube los hallazgos de código normalizados y la decisión de política del pipeline al registro de CI existente.

Petición

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
  }
}'

Respuesta200 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
}

La respuesta inmediata puede seguir en running mientras el procesamiento asíncrono actualiza los contadores y policy_result. Consulta GET /ci-scans/{ci_scan_id} para obtener el registro final.

Elige la acción de reprocesamiento correcta

Todas estas operaciones conservan el trabajo existente, pero resuelven problemas distintos. No llevan cuerpo en la petición y devuelven el escaneo o el hallazgo actualizado.

POST/scans/{scan_id}/retry

Reintenta un escaneo interrumpido

Úsalo con escaneos en cola, fallidos, en pausa o claramente atascados en ejecución. Se conservan los puntos de control recuperables.

Mostrar petición y respuesta

Petición

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"

Respuesta200 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
}

Un escaneo en ejecución sano y otros estados finales devuelven 400. La respuesta es el mismo escaneo encolado de nuevo; resume_count aumenta.

POST/scans/{scan_id}/resume

Reanuda desde los puntos de control

Recupera la orquestación a partir de los puntos de control y artefactos guardados. Un objetivo en pausa debe estar accesible primero.

Mostrar petición y respuesta

Petición

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"

Respuesta200 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
}

La respuesta conserva el progreso existente y encola la orquestación. Un objetivo en pausa inaccesible o un estado no admitido devuelve 400.

POST/scans/{scan_id}/verification-rerun

Vuelve a comprobar los hallazgos abiertos

Usa el mismo escaneo y los ids de hallazgo existentes sin consumir cupo de escaneos nuevos. Si falta la salida de una herramienta general, el resultado queda como no concluyente.

Mostrar petición y respuesta

Petición

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"

Respuesta200 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"
    }
  }
}

Requiere un escaneo completado o fallido con hallazgos abiertos elegibles. En caso contrario, la API devuelve 400 en lugar de iniciar una verificación vacía.

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

Vuelve a ejecutar un escáner

Sustituye la salida conservada de esa herramienta y concilia los nuevos resultados observados en el mismo escaneo.

Mostrar petición y respuesta

Petición

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"

Respuesta200 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"
    }
  }
}

Usa un id de herramienta canónico de GET /scans/available-tools. Una herramienta desconocida o un estado de escaneo no admitido devuelve 400.

POST/scans/{scan_id}/rehydrate-findings

Recupera los hallazgos guardados

Reconstruye los hallazgos de la base de datos a partir de los artefactos conservados. No envía nuevo tráfico de seguridad al objetivo.

Mostrar petición y respuesta

Petición

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"

Respuesta200 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
}

Úsalo solo cuando exista salida conservada. Si las salidas guardadas no contienen hallazgos, la API devuelve 400 y deja el escaneo sin cambios.

POST/findings/{finding_id}/verify-fix

Reproduce una PoC

Encola una reproducción acotada de los intercambios de control y de prueba registrados para un hallazgo de error SQL diferencial.

Mostrar petición y respuesta

Petición

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"

Respuesta200 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
  }
}

La respuesta inicial es pending; consulta GET /findings/{finding_id}. Una corrección verificada pasa el hallazgo a fixed. La falta de evidencias, los objetivos inaccesibles y las clases no admitidas quedan como no concluyentes.

Endpoints habituales

Este catálogo compacto cubre el flujo de automatización principal. Usa Swagger o ReDoc (arriba) para perfiles de autenticación, programaciones, claves de API, webhooks, uso, eventos en vivo, salidas de herramientas y esquemas de rutas públicas.

Objetivos

GET /targetsListar objetivos
POST /targetsCrear objetivo
GET /targets/{target_id}Obtener objetivo
PATCH /targets/{target_id}Actualizar objetivo
DELETE /targets/{target_id}Borrado lógico de un objetivo nunca escaneado o inactivo durante seis meses

Escaneos

GET /scans/available-toolsCatálogo de herramientas
GET /scansListar escaneos
POST /scansCrear y encolar escaneo
GET /scans/{scan_id}Obtener el estado del escaneo y la evaluación de la ejecución
POST /scans/{scan_id}/cancelCancelar un escaneo activo
POST /scans/{scan_id}/retryRecuperar un escaneo en cola, fallido, en pausa o atascado
POST /scans/{scan_id}/verification-rerunVolver a comprobar los hallazgos abiertos
POST /scans/{scan_id}/tools/{tool_name}/rerunVolver a ejecutar una herramienta
POST /scans/{scan_id}/resumeReanudar desde los puntos de control y artefactos guardados
POST /scans/{scan_id}/rehydrate-findingsReconstruir hallazgos a partir de la salida conservada

Hallazgos

GET /findingsListar hallazgos (filtros: target_id, scan_id, severity, status)
GET /findings/{finding_id}Obtener evidencias y detalle de reproducción
GET /findings/{finding_id}/tool-outputObtener la salida conservada de la herramienta de origen (404 si no existe o ha caducado)
PATCH /findings/{finding_id}Actualizar campos de clasificación
POST /findings/{finding_id}/verify-fixReproducir una PoC concreta

Informes

GET /reports/scans/{scan_id}Exportar JSON, CSV, PDF, Markdown, Jira o paquete de evidencias
GET /reports/targets/{target_id}Consolidar hallazgos activos; el último escaneo fija los metadatos del informe

Escaneos de CI / PR

Estas rutas ingieren resultados de PR/código y requieren ci:scan:write. POST /ci-scans/start crea un registro de seguimiento; no lanza DAST de web/API. Una misma clave puede incluir los ámbitos de CI y REST.

POST /ci-scans/startCrear un registro de PR/comprobación para la ingesta de resultados
POST /ci-scans/{ci_scan_id}/resultsEnviar resultados
GET /ci-scans/{ci_scan_id}Consultar el resultado del procesamiento

Errores

Los errores usan un campo detail. Puede ser un texto, un error de consentimiento estructurado o una lista de problemas de validación de campos.

Autenticación no válida401

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

Falta un ámbito o un rol403

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

Cuerpo de la petición no válido422

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

400

Filtros, transición de estado, alcance, consentimiento o semántica de la petición no válidos.

401

Credenciales ausentes, caducadas, revocadas o no válidas por otro motivo.

403

Identidad válida sin el plan, ámbito, rol en el espacio de trabajo o derecho necesario.

404

El objetivo, escaneo, hallazgo, registro de CI o salida conservada de la herramienta no existe en este espacio de trabajo.

429

Se ha superado la tasa de modificaciones. Lee Retry-After y las cabeceras X-RateLimit antes de reintentar.

Límites de tasa

Las peticiones que modifican datos pueden devolver 429 con las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y Retry-After.

Toma las cabeceras de respuesta como referencia y usa un backoff acotado. La creación de escaneos puede tener límites más estrictos que las modificaciones habituales.

Retry-After: 3600

Más ayuda

Consulta el centro de documentación, los enlaces de OpenAPI de arriba o contacta con soporte.

Referencia de la API

Conéctate de forma segura

Autenticación

Cabecera del espacio de trabajo

URL base

OpenAPI interactivo

Del objetivo al resultado verificado

Registra el objetivo

Encola un escaneo

Espera a un estado final

Consume las evidencias

Exporta el informe

Campos que importan en la automatización

Estado y cobertura del escaneo

Control de vulnerabilidades confirmadas

Evidencias y reproducibilidad

Paginación

Peticiones y respuestas

Ingesta de resultados de CI / PR

Elige la acción de reprocesamiento correcta

Reintenta un escaneo interrumpido

Reanuda desde los puntos de control

Vuelve a comprobar los hallazgos abiertos

Vuelve a ejecutar un escáner

Recupera los hallazgos guardados

Reproduce una PoC

Endpoints habituales

Errores

Límites de tasa

Más ayuda