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 the request is accepted. 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.

Recover a retest credential

When retest_failure_code identifies an authentication failure or an unavailable credential, retry with a replacement credential from the same target. The public retest request accepts target_credential_id for a replacement primary credential. To review both accounts for a dual-credential finding, use the dashboard. Replacement is allowed only after a qualifying credential failure. It changes future retest credentials, not the credentials recorded for the original finding. Inspect retest_failure_reason for the customer-visible explanation. See Retesting findings.

Record a false positive

When updating a finding’s lifecycle status, a false-positive decision uses status: "ARCHIVED", resolve_reason: "FALSE_POSITIVE", and a nonempty resolve_context explaining the decision. FIX and WONT_FIX are resolution reasons for RESOLVED findings. See the status endpoint schema for the complete request contract.

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

Recover a retest credential

Record a false positive

​List findings

​Query parameters

​Response

​Match the dashboard

​Examples

​Get finding details

​Update status

​Override severity

​Retest a finding

​Comments

​Patch summaries

​Analytics

​MCP

​Recover a retest credential

​Record a false positive

List findings

Query parameters

Response

Match the dashboard

Examples

Get finding details

Update status

Override severity

Retest a finding

Comments

Patch summaries

Analytics

MCP

Recover a retest credential

Record a false positive