API

Findings

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

Use the findings API to integrate repository findings, Web app findings, and GitHub advisories with your own security workflows.

All requests require the Bearer authentication described in the API overview.

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 repository_red_team, web_app_red_team, or github_advisory
triage_status string All new, triaging, in_review, or resolved 
curl "https://superagent.sh/api/v1/findings?kind=repository_red_team&triage_status=new&limit=50" \
  -H "Authorization: Bearer sk_live_..."

Response

200 OK

{
  "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, report, and pull-request context.

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

Response

200 OK

{
  "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."
        }
      ],
      "pull_request": {
        "status": "idle",
        "url": null,
        "branch": null,
        "started_at": null,
        "completed_at": 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:10:00.000Z"
  }
}

Finding fields

Field Type Description
id string Finding UUID
object string Always finding
kind string repository_red_team, web_app_red_team, or github_advisory
report_id string Source report UUID; for a GitHub advisory, this is the advisory UUID
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 Parent report status for report findings, or advisory state for GitHub advisories
triage object Automated and manual triage state
remediation object Proposed remediation and pull-request state
board_position number or null Position on the findings board
report object Source report summary
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
pull_request.status string idle, creating, created, or failed
pull_request.url string or null Pull-request URL
pull_request.branch string or null Pull-request branch
pull_request.started_at string or null Pull-request creation start time
pull_request.completed_at string or null Pull-request creation completion time

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

report.repository contains the GitHub repository URL for repository and GitHub advisory findings, and the tested target URL for Web app findings.

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 Web app findings 
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.

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.

Findings cannot be created manually. They originate from reports and GitHub advisories.

Trigger finding triage

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

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

Response

202 Accepted

{
  "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