Compliance Scans

Policies API v1 endpoints for compliance scan schedules and on-demand scans.

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	`GET`	`/compliance/kyverno/config`
Create or update a scan schedule	`POST`	`/compliance/kyverno/config`
Delete a scan schedule	`DELETE`	`/compliance/kyverno/config/{id}`
Run an on-demand compliance scan	`POST`	`/compliance/kyverno/reports/trigger`

Reference

List compliance scan schedules

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

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

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

Delete a scan schedule

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

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

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