> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt.


List, retrieve, update, delete, and triage security findings through the REST API.

# Findings

Use the findings API to integrate findings from Superagent security workers,
customer-provided security agents, and connected advisory sources with your own
security workflows.

All requests require the Bearer authentication described in the [REST API](https://www.superagent.sh/docs/api).

## List findings

`GET /api/v1/findings` returns paginated finding summaries.

### Query parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | integer | `25` | Number of results, from 1 through 100 |
| `offset` | integer | `0` | Number of matching results to skip; minimum 0 |
| `kind` | string | All | Source-specific finding kind, such as `repository_red_team`, `web_app_red_team`, or `github_advisory` |
| `triage_status` | string | All | `new`, `triaging`, `in_review`, or `resolved` |

```bash
curl "https://superagent.sh/api/v1/findings?kind=repository_red_team&triage_status=new&limit=50" \
  -H "Authorization: Bearer sk_live_..."
```

### Response

`200 OK`

```json
{
  "data": [
    {
      "id": "finding_uuid",
      "object": "finding",
      "kind": "repository_red_team",
      "report_id": "report_uuid",
      "title": "SQL injection in search endpoint",
      "description": "User input is interpolated into a SQL query.",
      "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H",
      "severity": null,
      "risk_level": "high",
      "weakness": "CWE-89",
      "cwe_ids": ["CWE-89"],
      "advisory_url": null,
      "source": "superagent",
      "status": "in_review",
      "triage_status": "new",
      "triage_resolution": null,
      "board_position": 1000,
      "report": {
        "repository": "https://github.com/acme/web",
        "label": "acme/web",
        "status": "in_review"
      },
      "created_at": "2026-07-22T07:00:00.000Z",
      "updated_at": "2026-07-22T07:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "has_more": false
  }
}
```

`has_more` is `true` when another page is available. Add the current `limit` to `offset` to request the next page.

List items expose `triage_status` and `triage_resolution` as top-level fields. They do not include the detailed `triage`, `remediation`, or `affected_products` fields returned by the retrieve endpoint.

## Retrieve a finding

`GET /api/v1/findings/{finding_id}` returns full triage, remediation, and report context.

```bash
curl https://superagent.sh/api/v1/findings/finding_uuid \
  -H "Authorization: Bearer sk_live_..."
```

### Response

`200 OK`

```json
{
  "data": {
    "id": "finding_uuid",
    "object": "finding",
    "kind": "repository_red_team",
    "report_id": "report_uuid",
    "title": "SQL injection in search endpoint",
    "description": "User input is interpolated into a SQL query.",
    "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H",
    "severity": null,
    "risk_level": "high",
    "weakness": "CWE-89",
    "cwe_ids": ["CWE-89"],
    "affected_products": [],
    "advisory_url": null,
    "source": "superagent",
    "status": "in_review",
    "triage": {
      "status": "in_review",
      "resolution": null,
      "summary": "The vulnerable query is reachable by authenticated users.",
      "recommendation": "Use a parameterized query.",
      "report_markdown": "## Verification\n\nThe issue was reproduced.",
      "verification_status": "confirmed",
      "evidence": {
        "request": "GET /api/search?q=test"
      },
      "started_at": "2026-07-22T07:05:00.000Z",
      "completed_at": "2026-07-22T07:10:00.000Z"
    },
    "remediation": {
      "proposed_patch": {
        "summary": "Use a parameterized query.",
        "diff": "diff --git a/app/api/search/route.ts...",
        "files": ["app/api/search/route.ts"]
      },
      "code_references": [
        {
          "file": "app/api/search/route.ts",
          "lineStart": 42,
          "lineEnd": 44,
          "symbol": "GET",
          "excerpt": "const result = await sql(query)",
          "reason": "The query includes untrusted input."
        }
      ]
    },
    "board_position": 1000,
    "report": {
      "repository": "https://github.com/acme/web",
      "label": "acme/web",
      "status": "in_review"
    },
    "created_at": "2026-07-22T07:00:00.000Z",
    "updated_at": "2026-07-22T07:10:00.000Z"
  }
}
```

### Finding fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Finding UUID |
| `object` | string | Always `finding` |
| `kind` | string | Source-specific finding kind |
| `report_id` | string | Source record UUID when the finding has one |
| `title` | string | Finding title |
| `description` | string | Detailed finding description |
| `cvss_vector` | string or null | CVSS vector |
| `severity` | string or null | Source severity |
| `risk_level` | string or null | Normalized risk level |
| `weakness` | string | Primary weakness or CWE |
| `cwe_ids` | string[] | CWE identifiers |
| `affected_products` | object[] | Affected product metadata |
| `advisory_url` | string or null | Source advisory URL |
| `source` | string | Finding source |
| `status` | string or null | Source record status |
| `triage` | object | Automated and manual triage state |
| `remediation` | object | Proposed remediation and code references |
| `board_position` | number or null | Position on the findings board |
| `report` | object | Source record summary when available |
| `created_at` | string | Creation time |
| `updated_at` | string | Last update time |

The `triage` object contains:

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | `new`, `triaging`, `in_review`, or `resolved` |
| `resolution` | string or null | `fixed`, `accepted_risk`, `false_positive`, or `wont_fix` |
| `summary` | string or null | Automated triage summary |
| `recommendation` | string or null | Recommended action |
| `report_markdown` | string or null | Full triage report in Markdown |
| `verification_status` | string or null | `confirmed`, `not_reproducible`, `inconclusive`, or `heuristic` |
| `evidence` | JSON value or null | Structured evidence captured during triage |
| `started_at` | string or null | Triage start time |
| `completed_at` | string or null | Triage completion time |

The `remediation` object contains:

| Field | Type | Description |
| --- | --- | --- |
| `proposed_patch` | object or null | Patch `summary`, unified `diff`, and affected `files` |
| `code_references` | object[] | References with `file`, optional `lineStart`, `lineEnd`, and `symbol`, plus `excerpt` and `reason` |

Each `affected_products` entry contains `ecosystem`, `packageName`, and `affectedVersions`. `ecosystem` can be an empty string when no ecosystem is known.

For repository and GitHub advisory findings, `report.repository` contains the GitHub repository URL. For application findings, it contains the tested target URL. Other finding kinds expose their source context through the fields defined for that source.

Findings outside the API key's organization return `404 not_found`, the same response used for an unknown finding ID.

## Update a finding

`PATCH /api/v1/findings/{finding_id}` updates the finding's triage lifecycle.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `triage_status` | string | Yes | `new`, `in_review`, or `resolved` |
| `triage_resolution` | string or null | When resolving | `fixed`, `accepted_risk`, `false_positive`, or `wont_fix` |
| `board_position` | number, numeric string, or null | No | Position on the findings board; unsupported for application findings |

```bash
curl https://superagent.sh/api/v1/findings/finding_uuid \
  -X PATCH \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "triage_status": "resolved",
    "triage_resolution": "fixed",
    "board_position": 1000
  }'
```

The endpoint returns `200 OK` with the full finding payload. Resolving without `triage_resolution` returns `400 invalid_request`.

## Delete a finding

`DELETE /api/v1/findings/{finding_id}` permanently deletes a finding. This action cannot be undone.

```bash
curl https://superagent.sh/api/v1/findings/finding_uuid \
  -X DELETE \
  -H "Authorization: Bearer sk_live_..."
```

The endpoint returns `204 No Content` with an empty response body.

The generic findings endpoint does not create findings manually. Superagent
security workers, customer-provided security agents, and connected advisory
sources create findings through their own interfaces.

## Trigger finding triage

`POST /api/v1/findings/{finding_id}/triage` starts billable automated triage. The request has no body.

```bash
curl https://superagent.sh/api/v1/findings/finding_uuid/triage \
  -X POST \
  -H "Authorization: Bearer sk_live_..."
```

### Response

`202 Accepted`

```json
{
  "data": {
    "id": "finding_uuid",
    "object": "finding",
    "kind": "repository_red_team",
    "triage_status": "triaging"
  }
}
```

If triage is already active, the endpoint returns `409 conflict`.

## Errors

| HTTP status | Code | Meaning |
| --- | --- | --- |
| `400` | `invalid_request` | Invalid field, query parameter, or state transition |
| `401` | `unauthorized` | Missing or invalid API key |
| `404` | `not_found` | Finding does not exist or belongs to another organization |
| `409` | `conflict` | Triage is already in progress |
| `500` | `internal_error` | Unexpected server failure |

## Next steps

- [Understand findings and reports](https://www.superagent.sh/docs/concepts/findings-and-reports)
- [Work with findings through Superagent MCP](https://www.superagent.sh/docs/mcp)
- [Subscribe to finding events with Webhooks](https://www.superagent.sh/docs/webhooks)

---
Source: https://www.superagent.sh/docs/api/findings
Index: https://www.superagent.sh/llms.txt