> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindfort.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia de la API de hallazgos

> Lista, filtra, clasifica, vuelve a probar y comenta hallazgos de MindFort mediante la API REST y MCP, y replica las pestañas del panel con filtros de estado.

Usa `GET /v1/findings` (clave de API) o la herramienta MCP `list_findings` (OAuth) para explorar hallazgos mediante programación. Ambas interfaces usan los mismos filtros y devuelven los mismos campos de resumen.

## Listar hallazgos

```bash theme={null}
curl -G "https://api.mindfort.app/v1/findings" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "target_id=${MINDFORT_TARGET_ID}" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "exclude_secured=true" \
  --data-urlencode "sort_by=severity" \
  --data-urlencode "limit=25"
```

### Parámetros de consulta

| Parámetro | Valor predeterminado | Descripción |
| - | - | - |
| `target_id` | — | Filtrar por un objetivo (UUID de **Target Inventory**) |
| `assessment_id` | — | Filtrar por hallazgos de una ejecución de evaluación (UUID de **Assessments**) |
| `status` | `ACTIVE` | Filtro de ciclo de vida: `ACTIVE`, `RESOLVED` o `ARCHIVED` |
| `exclude_secured` | `false` | Cuando es `true`, omite las sondas informativas seguras (`severity=secured`) |
| `severity` | — | Filtrar por severidad: `critical`, `high`, `medium`, `low` o `secured` (`info` es un alias obsoleto de `secured`) |
| `sort_by` | `severity` | `severity` (primero la puntuación más alta) o `created_at` |
| `order_direction` | `desc` | Dirección de ordenación: `asc` o `desc` |
| `search` | — | Buscar por ID, título, descripción, endpoint o impacto del hallazgo |
| `status_filter` | — | Filtro de vulnerabilidad: `vulnerable`, `secured` o `all` |
| `active_only` | `false` | Cuando es `true`, devuelve solo hallazgos activos |
| `org_wide` | `false` | Parámetro de compatibilidad; omite `target_id` y `assessment_id` para obtener resultados de toda la organización |
| `assigned_to_me` | `false` | Cuando es `true`, devuelve solo los hallazgos asignados al usuario actual |
| `assigned_to` | — | Filtrar por ID de usuario asignado |
| `unassigned` | `false` | Cuando es `true`, devuelve solo los hallazgos sin persona asignada |
| `finding_type` | — | Solo los hallazgos `red-team` están disponibles mediante la API pública |
| `limit` | `25` | Tamaño de página (máximo `100`) |
| `offset` | `0` | Desplazamiento para la paginación |

### Respuesta

Cada elemento de `findings` incluye:

| Campo | Descripción |
| - | - |
| `id` | UUID del hallazgo |
| `assessment_id` | UUID de la evaluación cuando está asociado a una evaluación |
| `target_name` | Nombre del objetivo cuando está disponible |
| `finding_type` | Siempre `red-team` |
| `title` | Título del hallazgo |
| `severity` | `critical`, `high`, `medium`, `low` o `secured` |
| `severity_score` | Puntuación numérica (puede ser `0` para elementos de severidad baja o seguros) |
| `overridden_severity` | Anulación de severidad seleccionada por el usuario cuando se ha establecido |
| `status` | `ACTIVE`, `RESOLVED` o `ARCHIVED` |
| `target_id` | UUID del objetivo |
| `created_at` | Marca de tiempo ISO 8601 |
| `updated_at` | Marca de tiempo ISO 8601 del último cambio visible del hallazgo |
| `retest_status` | Estado de ejecución actual de la nueva prueba cuando existe una |
| `retest_started_at` | Cuándo comenzó a ejecutarse la nueva prueba actual |
| `retest_completed_at` | Cuándo se completó o falló la nueva prueba actual |
| `retest_failure_reason` | Motivo visible para el cliente por el que no se pudo ejecutar una nueva prueba |
| `retest_in_progress` | `true` mientras una nueva prueba está en cola o en ejecución |

La respuesta también incluye `total`, `limit`, `offset` y `next_cursor` para la paginación. Usa `offset` hasta que `offset + len(findings) >= total`; `next_cursor` es un marcador de paginación opaco.

### Coincidir con el panel

La interfaz de MindFort usa pestañas y filtros que se corresponden con parámetros de la API:

| Vista del panel | Equivalente en API / MCP |
| - | - |
| **Open** (solo vulnerables, predeterminada) | `status=ACTIVE` y `exclude_secured=true` |
| **Open** (incluye sondas seguras) | `status=ACTIVE` (omite `exclude_secured` o usa `exclude_secured=false`) |
| **Resolved** | `status=RESOLVED` |
| **Archived** | `status=ARCHIVED` |
| Hallazgos de una evaluación | `assessment_id=<uuid>` |

> [!NOTE]
>
> Sin `exclude_secured=true`, los resultados de la lista incluyen hallazgos informativos de sondas **secured** (`severity=secured`) que el panel oculta en la pestaña Open predeterminada. Esto puede explicar por qué los recuentos de la API o de MCP parecen más altos que los de la interfaz.

### Ejemplos

**Vulnerabilidades de un objetivo (coincide con la pestaña Open predeterminada):**

```bash theme={null}
curl -G "https://api.mindfort.app/v1/findings" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "target_id=${MINDFORT_TARGET_ID}" \
  --data-urlencode "exclude_secured=true"
```

**Hallazgos de una evaluación específica:**

```bash theme={null}
curl -G "https://api.mindfort.app/v1/findings" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "assessment_id=${MINDFORT_ASSESSMENT_ID}" \
  --data-urlencode "exclude_secured=true"
```

**Hallazgos archivados:**

```bash theme={null}
curl -G "https://api.mindfort.app/v1/findings" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "target_id=${MINDFORT_TARGET_ID}" \
  --data-urlencode "status=ARCHIVED"
```

## Obtener los detalles de un hallazgo

```bash theme={null}
curl "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}"
```

Devuelve todos los campos, incluidos `description`, `impact`, `evidence`, `approach`, `remediation_advice`, `status` y el contexto de decisión de la nueva prueba.

Usa `retest_status` para interpretar la ejecución actual:

* `QUEUED`: aceptada, pero aún no se está ejecutando
* `RUNNING`: la ejecución está en curso
* `FAILED`: la ejecución no pudo completarse; revisa `retest_failure_reason`
* `COMPLETED`: la validación terminó y su resultado se aplicó al ciclo de vida del hallazgo

## Actualizar el estado

```bash theme={null}
curl -X POST "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/status" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"status":"RESOLVED","resolve_reason":"FIX"}'
```

Valores válidos: `ACTIVE`, `RESOLVED`, `ARCHIVED`. Cuando `status` es `RESOLVED`, puedes incluir `resolve_reason` (`FIX` o `WONT_FIX`) y, opcionalmente, `resolve_context` (máximo 2000 caracteres).

Las actualizaciones masivas están disponibles en `POST /v1/findings/status` con hasta 50 `finding_ids`.

## Anular la severidad

```bash theme={null}
curl -X PATCH "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/severity" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"severity":"high"}'
```

Valores aceptados: `critical`, `high`, `medium`, `low`, `secured`. Pasa `null` para eliminar una anulación. `info` solo se acepta como alias obsoleto de `secured`.

## Volver a probar un hallazgo

```bash theme={null}
curl -X POST "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/retest" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}"
```

Inicia una nueva prueba asíncrona para un hallazgo `ACTIVE`, `RESOLVED` o `ARCHIVED`. La solicitud falla si ya hay otra nueva prueba en cola o en ejecución.

Consulta `GET /v1/findings/{finding_id}` periódicamente después de que se acepte la solicitud. Cuando la nueva prueba se completa, MindFort aplica el resultado de la validación:

* Un resultado que indica que el problema está corregido en las condiciones probadas establece el hallazgo en `RESOLVED`.
* Un resultado que indica que el problema sigue siendo reproducible establece el hallazgo en `ACTIVE`.
* Un fallo de ejecución deja el resultado de seguridad sin cambios y rellena `retest_failure_reason`.

Las transiciones de la nueva prueba a `RUNNING` y `FAILED` actualizan el campo `updated_at` del hallazgo, por lo que los consumidores basados en cambios pueden detectarlas.

## Comentarios

```bash theme={null}
curl -G "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/comments" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "limit=25"
```

```bash theme={null}
curl -X POST "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/comments" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"content":"Patched in PR #482 — ready for retest."}'
```

Edita con `PATCH /v1/findings/{finding_id}/comments/{comment_id}` y elimina con `DELETE /v1/findings/{finding_id}/comments/{comment_id}`.

## Resúmenes de parches

```bash theme={null}
curl -G "https://api.mindfort.app/v1/findings/patches" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "limit=50"
```

Devuelve los hallazgos que tienen actividad de parches, incluidos `pr_url`, `patch_status` y `patch_state`. Usa `assigned_to_me=true` para limitar los resultados a los hallazgos del usuario actual o `search` para buscar por ID, título, descripción, endpoint o impacto del hallazgo. Las organizaciones autorizadas reciben la URL almacenada del pull request de GitHub, incluidas las URL de repositorios privados. La actividad de parches es independiente del estado del ciclo de vida del hallazgo.

## Analíticas

Los endpoints de analíticas de hallazgos aceptan un `target_id` opcional. Omítelo para obtener métricas de toda la organización. `GET /v1/findings/severity-score-history` acepta `granularity` (`day`, `week` o `month`), y las métricas de remediación aceptan además las fechas inclusivas opcionales `from` y `to`.

| Endpoint | Descripción |
| - | - |
| `GET /v1/findings/counts` | Recuentos de ciclo de vida, exposición y severidad |
| `GET /v1/findings/severity-distribution` | Distribución por severidad |
| `GET /v1/findings/category-distribution` | Distribución por OWASP y etiquetas de vulnerabilidad |
| `GET /v1/findings/severity-score-history` | Historial de puntuación de severidad |
| `GET /v1/findings/metrics/current` | Métricas de seguridad actuales |
| `GET /v1/findings/metrics/timeseries` | Métricas de series temporales (`from`, `to`, `granularity` opcional) |
| `GET /v1/findings/metrics/remediation` | Métricas de remediación (MTTR) |
| `GET /v1/findings/metrics/sla` | Métricas de incumplimiento de SLA |
| `GET /v1/findings/metrics/aging` | Rangos de antigüedad de los hallazgos |

La puntuación de salud del objetivo está disponible en `GET /v1/targets/{target_id}/health-score`.

## MCP

La [guía de MCP](https://docs.mindfort.ai/es/guides/mcp.md) expone los mismos filtros semánticos en la herramienta `list_findings`. Pasa `target_id`, `assessment_id`, `status`, `exclude_secured`, `severity`, `sort_by`, `order_direction`, `search` o filtros de asignación; las herramientas de colecciones de MCP usan un `cursor` opaco en lugar de un desplazamiento sin procesar.

Después de una actualización del servidor, **no** necesitas reinstalar MCP. Mantén la misma URL `https://api.mindfort.app/mcp` y reinicia tu agente o inicia un chat nuevo para que cargue el esquema de herramientas más reciente.

## Recuperar una credencial de nueva prueba

Cuando `retest_failure_code` identifica un fallo de autenticación o una credencial no disponible, vuelve a intentarlo con una credencial sustituta del mismo objetivo. La solicitud pública de nueva prueba acepta `target_credential_id` para una credencial principal sustituta. Para revisar ambas cuentas de un hallazgo con credenciales duales, usa el panel.

La sustitución solo se permite después de un fallo de credencial que cumpla los requisitos. Cambia las credenciales de futuras nuevas pruebas, no las credenciales registradas para el hallazgo original. Revisa `retest_failure_reason` para ver la explicación visible para el cliente. Consulta [Volver a probar hallazgos](https://docs.mindfort.ai/es/guides/retesting.md).

## Registrar un falso positivo

Al actualizar el estado del ciclo de vida de un hallazgo, una decisión de falso positivo usa `status: "ARCHIVED"`, `resolve_reason: "FALSE_POSITIVE"` y un `resolve_context` no vacío que explique la decisión. `FIX` y `WONT_FIX` son motivos de resolución para hallazgos `RESOLVED`. Consulta el esquema del endpoint de estado para ver el contrato completo de la solicitud.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.