Findings

List Findings

GET /api/v1/findings

Returns security findings for your organization with optional filters.

curl -H "X-API-Key: sb_live_abc123def456" \
  "https://api.surfbot.io/api/v1/findings?severity=critical,high&status=open&limit=50"

Query Parameters:

Parameter	Type	Description
`domain_id`	string	Filter by domain UUID
`severity`	string	Comma-separated: `critical`, `high`, `medium`, `low`, `info`
`status`	string	Comma-separated: `open`, `acknowledged`, `resolved`, `false_positive`
`source_tool`	string	Comma-separated tool names (e.g. `nuclei`, `subfinder`)
`limit`	integer	Max results (default: unset)
`offset`	integer	Skip N results for pagination

Response (200):

{
  "findings": [
    {
      "id": "aa0e8400-e29b-41d4-a716-446655440000",
      "org_id": "110e8400-e29b-41d4-a716-446655440000",
      "asset_id": "220e8400-e29b-41d4-a716-446655440000",
      "template_id": "http-missing-security-headers",
      "template_name": "HTTP Missing Security Headers",
      "severity": "medium",
      "title": "Missing Content-Security-Policy Header",
      "description": "The Content-Security-Policy header is not set.",
      "reference": [
        "https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP"
      ],
      "remediation": "Add a Content-Security-Policy header to your server configuration.",
      "evidence": "GET https://api.example.com/ -> No CSP header found",
      "cvss": 5.3,
      "cve": "",
      "status": "open",
      "first_seen": "2026-01-10T00:00:00Z",
      "last_seen": "2026-03-15T10:17:30Z",
      "resolved_at": null,
      "created_at": "2026-01-10T00:00:00Z",
      "updated_at": "2026-03-15T10:17:30Z",
      "source_tool": "nuclei",
      "confidence": 0.95,
      "ai_severity": null,
      "ai_rationale": ""
    }
  ],
  "count": 1
}

Get Finding

GET /api/v1/findings/:id

Returns full details for a specific finding including evidence, CVSS score, and template info.

curl -H "X-API-Key: sb_live_abc123def456" \
  https://api.surfbot.io/api/v1/findings/aa0e8400-e29b-41d4-a716-446655440000

Response (200):

{
  "id": "aa0e8400-e29b-41d4-a716-446655440000",
  "org_id": "110e8400-e29b-41d4-a716-446655440000",
  "asset_id": "220e8400-e29b-41d4-a716-446655440000",
  "template_id": "CVE-2024-1234",
  "template_name": "Example RCE Vulnerability",
  "severity": "critical",
  "title": "Remote Code Execution via API endpoint",
  "description": "A critical vulnerability allows unauthenticated remote code execution.",
  "reference": [
    "https://nvd.nist.gov/vuln/detail/CVE-2024-1234",
    "https://example.com/advisory"
  ],
  "remediation": "Update to version 2.1.0 or later.",
  "evidence": "POST /api/exec -> 200 OK with command output in response body",
  "cvss": 9.8,
  "cve": "CVE-2024-1234",
  "status": "open",
  "first_seen": "2026-03-15T10:17:30Z",
  "last_seen": "2026-03-15T10:17:30Z",
  "resolved_at": null,
  "created_at": "2026-03-15T10:17:30Z",
  "updated_at": "2026-03-15T10:17:30Z",
  "source_tool": "nuclei",
  "confidence": 0.98,
  "ai_severity": "critical",
  "ai_rationale": "Confirmed RCE with no authentication required. CVSS 9.8 is appropriate."
}

Finding fields:

Field	Description
`template_id`	Nuclei template or internal rule identifier
`template_name`	Human-readable template name
`severity`	`critical`, `high`, `medium`, `low`, or `info`
`evidence`	Proof of the finding (URL, response snippet, etc.)
`cvss`	CVSS v3 score (0-10)
`cve`	CVE identifier if applicable
`source_tool`	Scanner tool that produced the finding (e.g. `nuclei`)
`confidence`	Confidence score (0-1)
`ai_severity`	AI-adjusted severity (when available)
`ai_rationale`	AI explanation for severity adjustment
`status`	`open`, `acknowledged`, `resolved`, `false_positive`

List Findings

Get Finding

On this page