Findings

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

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

List findings

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

Query parameters

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, and report 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."
        }
      ]
    },
    "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

The triage object contains:

The remediation object contains:

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

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.

Finding comments

Comments are available on repository, application, agent, package, and GitHub advisory findings. Open the Comments tab in a finding's detail view to discuss evidence, progress, and decisions. Organization members can add comments and edit or delete their own comments. Owners can manage all comments. Organization API keys can manage all comments on findings in their organization.

Listing accepts limit (1–100, default 25) and offset (default 0). Creating and updating accept only body: non-empty Markdown text, up to 10,000 characters after trimming leading and trailing whitespace. Empty, whitespace-only, malformed, or oversized input returns 400 invalid_request.

curl https://superagent.sh/api/v1/findings/finding_uuid/comments \
  -X POST \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"body":"Verified the fix in staging. Ready for review."}'

Each comment includes id, object: "finding_comment", finding_id, body, author (type, user_id, and name), can_manage, created_at, and updated_at. API and MCP comments use author type api_key, a null user_id, and name API key. Editing retains the original author and creation time. Deleting a finding also deletes its comments. Unknown findings, comments on a different finding, and findings outside the caller's organization return 404 not_found.

The equivalent MCP tools are list_finding_comments, create_finding_comment, update_finding_comment, and delete_finding_comment.

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.

The generic findings endpoint does not create findings manually. Superagent features, 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.

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

Next steps

• Understand findings and reports
• Work with findings through Superagent MCP
• Subscribe to finding events with Webhooks