# Scans

Secret scanning for detecting hardcoded secrets

Source: https://keyenv.dev/docs/api/scans/

Secret scanning for detecting hardcoded secrets

## List scans

```http
GET /api/v1/projects/{projectId}/scans
```

Lists secret scan results for a project

**Operation ID:** `listScans` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | List of scans | `object[]` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `project_id` | `string (uuid)` |  |
| `source` | `enum (cli, action, app)` |  |
| `commit_sha` | `string` |  |
| `branch` | `string` |  |
| `findings_count` | `integer` |  |
| `created_at` | `string (date-time)` |  |
| `created_by` | `string (uuid)` |  |

### Example

```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/scans" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```

## Upload scan results

```http
POST /api/v1/projects/{projectId}/scans
```

Uploads secret scan results from CLI or GitHub Action

**Operation ID:** `uploadScan` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `findings` | `object[]` | no |  |
| `source` | `enum (cli, action, app)` | no |  |
| `commit_sha` | `string` | no |  |
| `branch` | `string` | no |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `201` | Scan uploaded | `UploadScanResponse` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`201`)

| Field | Type | Description |
| --- | --- | --- |
| `scan_id` | `string (uuid)` |  |
| `findings_count` | `integer` |  |

### Example

```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/scans" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"findings":[{"pattern_id":"string","pattern_name":"string","severity":"critical","file_path":"string","line_number":0,"matched_text":"string"}],"source":"cli","commit_sha":"string","branch":"string"}'
```

## Get scan

```http
GET /api/v1/projects/{projectId}/scans/{scanId}
```

Returns a scan with its findings

**Operation ID:** `getScan` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `scanId` | `string (uuid)` | yes |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Scan details with findings | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |

### Example

```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/scans/{scanId}" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```

## Update finding status

```http
PATCH /api/v1/projects/{projectId}/scans/{scanId}/findings/{findingId}
```

Updates a scan finding status (dismiss or reactivate)

**Operation ID:** `updateFindingStatus` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `scanId` | `string (uuid)` | yes |  |
| `findingId` | `string (uuid)` | yes |  |

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `enum (active, dismissed, fixed)` | yes |  |
| `dismissed_reason` | `string` | no |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Finding updated | `ScanFinding` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `scan_id` | `string (uuid)` |  |
| `pattern_id` | `string` |  |
| `pattern_name` | `string` |  |
| `severity` | `enum (critical, high, medium, low)` |  |
| `file_path` | `string` |  |
| `line_number` | `integer` |  |
| `snippet` | `string` |  |
| `status` | `enum (active, dismissed, fixed)` |  |
| `dismissed_by` | `string (uuid)` |  |
| `dismissed_at` | `string (date-time)` |  |
| `dismissed_reason` | `string` |  |
| `created_at` | `string (date-time)` |  |

### Example

```bash
curl -X PATCH "https://api.keyenv.dev/api/v1/projects/{projectId}/scans/{scanId}/findings/{findingId}" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"active","dismissed_reason":"string"}'
```