---
title: "Compliance Scans"
description: "Policies API v1 endpoints for compliance scan schedules and on-demand scans."
diataxis: reference
applies_to:
  product: "nirmata-control-hub"
audience: ["platform-engineer","developer"]
last_updated: 2026-10-06
url: https://docs.nirmata.io/docs/reference/rest-api/policies_api_v1/compliance_scans/
---


<!-- Generated by scripts/gen-policies-api-v1/gen.py. Edit inventory.json, not this file. -->

Configure scheduled compliance scans and run scans on demand.

All paths are relative to `/policies/api/v1`. See [Policies API v1](../) for authentication and conventions.

## Endpoints

| Operation | Method | Path |
|---|---|---|
| [List compliance scan schedules](#list-compliance-scan-schedules) | `GET` | `/compliance/kyverno/config` |
| [Create or update a scan schedule](#create-or-update-a-scan-schedule) | `POST` | `/compliance/kyverno/config` |
| [Delete a scan schedule](#delete-a-scan-schedule) | `DELETE` | `/compliance/kyverno/config/{id}` |
| [Run an on-demand compliance scan](#run-an-on-demand-compliance-scan) | `POST` | `/compliance/kyverno/reports/trigger` |

## Reference

### List compliance scan schedules

```http
GET /policies/api/v1/compliance/kyverno/config
```

Returns the scheduled compliance scan configuration for each target in the tenant (one per target), ordered by ID. Optionally filter to one target.

**Roles:** `admin`, `security`

**Query parameters**

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `targetId` | `string` | No | — | Only return the configuration for this target (UUID) |

**Response** `200` (`application/json`)

Array of ComplianceConfigDto (not paginated)

| Field | Type | Description |
|---|---|---|
| `id` | `string (uuid)` | Configuration ID |
| `tenantId` | `string (uuid)` | Tenant ID |
| `targetId` | `string (uuid)` | Target ID |
| `targetType` | `string` | Target type, e.g. cluster |
| `targetName` | `string` | Target display name |
| `enabled` | `boolean` | Whether scheduled scans run |
| `cronExpression` | `string` | 5-field cron schedule |
| `standards` | `string[]` | Standards in scope; null = all standards |
| `lastCheckedAt` | `string (date-time)` | Last schedule check |
| `lastRunAt` | `string (date-time)` | Last scan run |
| `createdAt` | `string (date-time)` | — |
| `updatedAt` | `string (date-time)` | — |

**Errors**

- `400` — targetId is not a valid UUID
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Create or update a scan schedule

```http
POST /policies/api/v1/compliance/kyverno/config
```

Upserts the scan schedule for a target: there is one configuration per target, so posting again for the same targetId updates it in place. cronExpression defaults to '0 2 * * *' (daily 02:00); standards null means every supported standard.

**Roles:** `admin`, `security`

**Request body** (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targetId` | `string (uuid)` | Yes | Target to scan |
| `targetType` | `string` | Yes | Target type, e.g. cluster |
| `targetName` | `string` | Yes | Target display name |
| `enabled` | `boolean` | No | Enable scheduled scans (defaults to false if omitted) |
| `cronExpression` | `string` | No | 5-field cron (minute hour dom month dow); default '0 2 * * *' |
| `standards` | `string[]` | No | Standard keys to scan; null/omitted = all standards |

**Response** `200` (`application/json`)

Empty body

**Errors**

- `400` — targetId not a UUID, missing required field, or cronExpression is not 5 fields
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

**Example**

```json
{"targetId":"3f1c...","targetType":"cluster","targetName":"prod-eks","enabled":true,"cronExpression":"0 2 * * *","standards":["soc2","cis-eks"]}
```

### Delete a scan schedule

```http
DELETE /policies/api/v1/compliance/kyverno/config/{id}
```

Removes a target's scan schedule configuration.

**Roles:** `admin`, `security`

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `id` | `string` | Configuration ID (UUID) from the list response, not the target ID |

**Response** `204`

No content

**Errors**

- `400` — id is not a valid UUID
- `404` — No such configuration in this tenant (empty body)
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Run an on-demand compliance scan

```http
POST /policies/api/v1/compliance/kyverno/reports/trigger
```

Starts an immediate compliance scan of one target, one report per standard. Runs asynchronously: returns 202 with the new report IDs, which can be polled via GET /compliance/kyverno/reports/{id}. On-demand scans always run even if nothing changed since the last scan.

**Roles:** `admin`, `security`

**Request body** (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targetId` | `string (uuid)` | Yes | Target to scan |
| `targetType` | `string` | Yes | Target type, e.g. cluster |
| `targetName` | `string` | Yes | Target display name |
| `standards` | `string[]` | No | Standards to scan; null/empty = all standards in the tenant catalog |

**Response** `202` (`application/json`)

ComplianceTriggerResponseDto

| Field | Type | Description |
|---|---|---|
| `reportIds` | `object` | Map of standard key to new report ID, e.g. {"soc2":"uuid"} |
| `message` | `string` | Human-readable status |
| `triggeredAt` | `string (date-time)` | Trigger time |

**Errors**

- `400` — targetId not a UUID (code INVALID_TARGET_ID) or required field missing
- `409` — A scan is already in progress for a requested target/standard (code SCAN_IN_PROGRESS; body includes existing reportId)
- `429` — Scan capacity exceeded (code SCAN_CAPACITY_EXCEEDED)
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

**Example**

```json
{"targetId":"3f1c...","targetType":"cluster","targetName":"prod-eks","standards":["soc2"]}
```