Findings API reference

Use GET /v1/findings (API key) or the MCP list_findings tool (OAuth) to browse findings programmatically. Both surfaces use the same filters and return the same summary fields.

List findings

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"

Query parameters

Parameter	Default	Description
`target_id`	—	Filter to one target (UUID from Target Inventory)
`assessment_id`	—	Filter to findings from one assessment run (UUID from Assessments)
`status`	`ACTIVE`	Lifecycle filter: `ACTIVE`, `RESOLVED`, or `ARCHIVED`
`exclude_secured`	`false`	When `true`, omit informational secured probes (`severity=secured`)
`severity`	—	Filter by severity: `critical`, `high`, `medium`, `low`, or `secured` (`info` is a deprecated alias for `secured`)
`sort_by`	`severity`	`severity` (highest score first) or `created_at`
`order_direction`	`desc`	Sort direction: `asc` or `desc`
`search`	—	Search finding ID, title, description, endpoint, or impact
`status_filter`	—	Vulnerability filter: `vulnerable`, `secured`, or `all`
`active_only`	`false`	When `true`, return only active findings
`org_wide`	`false`	Compatibility parameter; omit `target_id` and `assessment_id` for organization-wide results
`assigned_to_me`	`false`	When `true`, return only findings assigned to the current user
`assigned_to`	—	Filter by assignee user ID
`unassigned`	`false`	When `true`, return only findings without an assignee
`finding_type`	—	Only `red-team` findings are available through the public API
`limit`	`25`	Page size (max `100`)
`offset`	`0`	Offset for pagination

Response

Each item in findings includes:

Field	Description
`id`	Finding UUID
`assessment_id`	Assessment UUID when associated with an assessment
`target_name`	Target name when available
`finding_type`	Always `red-team`
`title`	Finding title
`severity`	`critical`, `high`, `medium`, `low`, or `secured`
`severity_score`	Numeric score (may be `0` for low-severity or secured items)
`overridden_severity`	User-selected severity override when one is set
`status`	`ACTIVE`, `RESOLVED`, or `ARCHIVED`
`target_id`	Target UUID
`created_at`	ISO 8601 timestamp
`updated_at`	ISO 8601 timestamp for the latest visible finding change
`retest_status`	Current retest execution state when a retest exists
`retest_started_at`	When the current retest began execution
`retest_completed_at`	When the current retest completed or failed
`retest_failure_reason`	Customer-visible reason a retest could not execute
`retest_in_progress`	`true` while a retest is queued or running

The response also includes total, limit, offset, and next_cursor for pagination. Use offset until offset + len(findings) >= total; next_cursor is an opaque pagination marker.

Match the dashboard

The MindFort UI uses tabs and filters that map to API parameters:

Dashboard view	API / MCP equivalent
Open (vulnerable only, default)	`status=ACTIVE` and `exclude_secured=true`
Open (include secured probes)	`status=ACTIVE` (omit `exclude_secured` or `exclude_secured=false`)
Resolved	`status=RESOLVED`
Archived	`status=ARCHIVED`
Findings from one assessment	`assessment_id=<uuid>`

Without exclude_secured=true, list results include informational secured probe findings (severity=secured) that the dashboard hides on the default Open tab. This is the most common reason API or MCP counts look higher than the UI.

Examples

Vulnerabilities for a target (matches default Open tab):

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"

Findings from a specific assessment:

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"

Archived findings:

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"

Get finding details

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

Returns full fields including description, impact, evidence, approach, remediation_advice, status, and retest decision context. Use retest_status to interpret the current run:

QUEUED: accepted but not yet executing
RUNNING: execution is in progress
FAILED: execution could not complete; inspect retest_failure_reason
COMPLETED: validation finished and its result was applied to the finding lifecycle

Update status

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

Valid values: ACTIVE, RESOLVED, ARCHIVED. When status is RESOLVED, you may include resolve_reason (FIX or WONT_FIX) and optional resolve_context (max 2000 characters). Bulk updates are available at POST /v1/findings/status with up to 50 finding_ids.

Override severity

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

Accepted values: critical, high, medium, low, secured. Pass null to clear an override. info is accepted only as a deprecated alias for secured.

Retest a finding

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

Starts an asynchronous retest for an ACTIVE, RESOLVED, or ARCHIVED finding. The request fails if another retest is already queued or running. Poll GET /v1/findings/{finding_id} after admission. When the retest completes, MindFort applies the validation result:

A fixed finding becomes RESOLVED.
A finding that remains vulnerable becomes ACTIVE.
An execution failure leaves the security outcome unchanged and populates retest_failure_reason.

Retest RUNNING and FAILED transitions update the finding’s updated_at, so change-based consumers can observe them.

Comments

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

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

Edit with PATCH /v1/findings/{finding_id}/comments/{comment_id} and delete with DELETE /v1/findings/{finding_id}/comments/{comment_id}.

Patch summaries

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

Returns findings that have patch activity, including pr_url, patch_status, and patch_state. Use assigned_to_me=true to restrict to the current user’s findings or search to match finding ID, title, description, endpoint, or impact. Authorized organizations receive the stored GitHub pull-request URL, including private repository URLs. Patch activity is independent of finding lifecycle status.

Analytics

Finding analytics endpoints accept an optional target_id. Omit it for organization-wide metrics. GET /v1/findings/severity-score-history accepts granularity (day, week, or month), and remediation metrics additionally accept optional inclusive from and to dates.

Endpoint	Description
`GET /v1/findings/counts`	Lifecycle, exposure, and severity counts
`GET /v1/findings/severity-distribution`	Severity distribution
`GET /v1/findings/category-distribution`	OWASP and vulnerability tag distribution
`GET /v1/findings/severity-score-history`	Severity score history
`GET /v1/findings/metrics/current`	Current security metrics
`GET /v1/findings/metrics/timeseries`	Timeseries metrics (`from`, `to`, optional `granularity`)
`GET /v1/findings/metrics/remediation`	Remediation metrics (MTTR)
`GET /v1/findings/metrics/sla`	SLA breach metrics
`GET /v1/findings/metrics/aging`	Finding age buckets

Target health score is available at GET /v1/targets/{target_id}/health-score.

MCP

The MCP guide exposes the same semantic filters on the list_findings tool. Pass target_id, assessment_id, status, exclude_secured, severity, sort_by, order_direction, search, or assignment filters; MCP collection tools use an opaque cursor rather than a raw offset. After a server update, you do not need to reinstall MCP — keep the same https://api.mindfort.app/mcp URL and restart your agent or start a new chat so it picks up the latest tool schema.

Overview

Endpoints

List findings

Query parameters

Response

Match the dashboard

Examples

Get finding details

Update status

Override severity

Retest a finding

Comments

Patch summaries

Analytics

MCP

​List findings

​Query parameters

​Response

​Match the dashboard

​Examples

​Get finding details

​Update status

​Override severity

​Retest a finding

​Comments

​Patch summaries

​Analytics

​MCP

List findings

Query parameters

Response

Match the dashboard

Examples

Get finding details

Update status

Override severity

Retest a finding

Comments

Patch summaries

Analytics

MCP