> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infraudit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API endpoints for vulnerability findings

> Trigger vulnerability scans, list CVE findings by severity and status, and retrieve full vulnerability details via the InfraAudit API.

The vulnerabilities endpoints expose CVE scan results from InfraAudit's Trivy and NVD integrations. You can trigger scans, filter findings by severity and status, and retrieve full vulnerability details including NVD descriptions and fix versions.

Base path: `/api/v1/vulnerabilities`

***

## POST /vulnerabilities/scan — trigger a scan

Starts a vulnerability scan. You can scope it to a specific provider or resource, or run it across all providers.

```http theme={null}
POST /api/v1/vulnerabilities/scan
Authorization: Bearer <token>
Content-Type: application/json
```

### Request body (optional)

<ParamField body="provider_id" type="integer">
  Scope the scan to a specific provider.
</ParamField>

<ParamField body="resource_id" type="integer">
  Scope the scan to a specific resource.
</ParamField>

```json theme={null}
{
  "provider_id": 1,
  "resource_id": 42
}
```

### Response `202`

```json theme={null}
{
  "job_id": 55,
  "status": "running"
}
```

***

## GET /vulnerabilities — list vulnerability findings

Returns a paginated list of vulnerability findings.

```http theme={null}
GET /api/v1/vulnerabilities
Authorization: Bearer <token>
```

### Query parameters

<ParamField query="provider_id" type="integer">
  Filter by provider.
</ParamField>

<ParamField query="resource_id" type="integer">
  Filter by resource.
</ParamField>

<ParamField query="severity" type="string">
  Filter by severity: `critical`, `high`, `medium`, or `low`.
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `open`, `fixed`, or `ignored`.
</ParamField>

<ParamField query="cve_id" type="string">
  Filter by a specific CVE ID, for example `CVE-2024-12345`.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number.
</ParamField>

<ParamField query="per_page" type="integer" default="20">
  Results per page. Maximum is 100.
</ParamField>

### Response

```json theme={null}
{
  "data": [
    {
      "id": 1,
      "cve_id": "CVE-2024-12345",
      "severity": "critical",
      "cvss_score": 9.8,
      "package_name": "openssl",
      "installed_version": "1.1.1t",
      "fix_version": "1.1.1u",
      "resource_id": 42,
      "resource_name": "api-pod",
      "status": "open",
      "detected_at": "2024-01-15T02:00:00Z"
    }
  ],
  "meta": { "total": 8, "page": 1, "per_page": 20 }
}
```

<ResponseField name="cvss_score" type="number">
  CVSS v3 base score (0.0–10.0).
</ResponseField>

<ResponseField name="fix_version" type="string">
  The earliest package version that patches this vulnerability. May be `null` if no fix is available.
</ResponseField>

***

## GET /vulnerabilities/{id} — get finding details

Returns full vulnerability details including the NVD description and reference links.

```http theme={null}
GET /api/v1/vulnerabilities/{id}
Authorization: Bearer <token>
```

***

## PATCH /vulnerabilities/{id} — update status

Update the status of a vulnerability finding, for example to mark it as ignored.

```http theme={null}
PATCH /api/v1/vulnerabilities/{id}
Authorization: Bearer <token>
Content-Type: application/json
```

### Request body

<ParamField body="status" type="string" required>
  New status: `open`, `fixed`, or `ignored`.
</ParamField>

<ParamField body="reason" type="string">
  Reason for the status change. Required when setting `ignored`.
</ParamField>

```json theme={null}
{
  "status": "ignored",
  "reason": "Not exploitable in this deployment"
}
```

***

## GET /vulnerabilities/summary — get summary

Returns aggregate counts by severity and status.

```http theme={null}
GET /api/v1/vulnerabilities/summary
Authorization: Bearer <token>
```