---
title: "Compliance Standards"
description: "Policies API v1 endpoints for compliance standards, enablement, and custom standards."
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_standards/
---


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

List the compliance standards available to your tenant, enable or disable them for clusters, trigger rescans, and manage custom standards that map Kyverno policies to your own controls.

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

## Endpoints

| Operation | Method | Path |
|---|---|---|
| [List custom compliance standards](#list-custom-compliance-standards) | `GET` | `/compliance/kyverno/custom-mappings` |
| [Create a custom compliance standard](#create-a-custom-compliance-standard) | `POST` | `/compliance/kyverno/custom-mappings` |
| [List compliance standards](#list-compliance-standards) | `GET` | `/compliance/kyverno/standards` |
| [Download an example custom standard](#download-an-example-custom-standard) | `GET` | `/compliance/kyverno/custom-mappings/example` |
| [Download the custom standard JSON Schema](#download-the-custom-standard-json-schema) | `GET` | `/compliance/kyverno/custom-mappings/schema` |
| [Get a custom compliance standard](#get-a-custom-compliance-standard) | `GET` | `/compliance/kyverno/custom-mappings/{standardKey}` |
| [Update a custom compliance standard](#update-a-custom-compliance-standard) | `PUT` | `/compliance/kyverno/custom-mappings/{standardKey}` |
| [Delete a custom compliance standard](#delete-a-custom-compliance-standard) | `DELETE` | `/compliance/kyverno/custom-mappings/{standardKey}` |
| [List enabled compliance standards](#list-enabled-compliance-standards) | `GET` | `/compliance/kyverno/standards/enabled` |
| [Rescan all enabled standards](#rescan-all-enabled-standards) | `POST` | `/compliance/kyverno/standards/rescan` |
| [Get a standard's control catalog](#get-a-standards-control-catalog) | `GET` | `/compliance/kyverno/standards/{standard}/controls` |
| [Enable a standard for targets](#enable-a-standard-for-targets) | `PUT` | `/compliance/kyverno/standards/{standard}/enablement` |
| [Update standard enablement flags](#update-standard-enablement-flags) | `PATCH` | `/compliance/kyverno/standards/{standard}/enablement` |
| [Disable a compliance standard](#disable-a-compliance-standard) | `DELETE` | `/compliance/kyverno/standards/{standard}/enablement` |
| [Get a standard's policy-to-control mapping](#get-a-standards-policy-to-control-mapping) | `GET` | `/compliance/kyverno/standards/{standard}/mappings` |
| [Rescan one compliance standard](#rescan-one-compliance-standard) | `POST` | `/compliance/kyverno/standards/{standard}/rescan` |

## Reference

### List custom compliance standards

```http
GET /policies/api/v1/compliance/kyverno/custom-mappings
```

Lists the custom compliance standards uploaded by this tenant.

**Roles:** `admin`, `platform`, `security`, `devops`

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

Array of custom standard summaries (not paginated)

| Field | Type | Description |
|---|---|---|
| `standardKey` | `string` | Unique key of the custom standard |
| `displayName` | `string` | — |
| `policyCount` | `integer` | Number of mapped policies |
| `controlCount` | `integer` | Distinct controls mapped |
| `adminState` | `string` | — |
| `createdBy` | `string` | — |
| `createdAt` | `string (date-time)` | — |
| `updatedAt` | `string (date-time)` | — |

**Errors**

- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Create a custom compliance standard

```http
POST /policies/api/v1/compliance/kyverno/custom-mappings
```

Uploads a YAML definition of a new custom standard. It is validated against the schema and then scanned, scored and reported exactly like a built-in standard. Non-blocking issues (e.g. policy names not yet managed in Nirmata) are returned in a warnings array.

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

**Request body** (`text/yaml (also application/x-yaml, text/plain)`)

| Field | Type | Required | Description |
|---|---|---|---|
| `standardKey` | `string` | Yes | Lowercase letters, digits, hyphens; must not match a built-in standard |
| `displayName` | `string` | Yes | — |
| `preferVpol` | `boolean` | No | Informational |
| `sources` | `object[]` | No | {id, title, ref, effective} |
| `policies` | `object` | Yes | Map of Kyverno policy name to {clusterScoped, controls[]}; unknown policy names produce warnings, not errors |
| `non-automatable` | `object[]` | No | {id, family, reason} controls reported as not automatable |

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

`Custom standard detail plus optional warnings: string[]`

| Field | Type | Description |
|---|---|---|
| `standardKey` | `string` | Unique key of the custom standard |
| `displayName` | `string` | — |
| `policyCount` | `integer` | Number of mapped policies |
| `controlCount` | `integer` | Distinct controls mapped |
| `adminState` | `string` | — |
| `createdBy` | `string` | — |
| `createdAt` | `string (date-time)` | — |
| `updatedAt` | `string (date-time)` | — |
| `preferVpol` | `boolean` | — |
| `sources` | `object[]` | {id, title, ref, effective} |
| `policies` | `object` | Map of policy name to {clusterScoped, controls} |
| `nonAutomatable` | `object[]` | {id, family, reason} |
| `rawYaml` | `string` | The uploaded YAML |
| `contentSha256` | `string` | — |
| `warnings` | `string[]` | Present only when there are warnings |

**Errors**

- `400` — YAML fails validation (code VALIDATION_FAILED)
- `409` — standardKey already exists for this tenant or collides with a built-in standard (code CONFLICT)
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

**Example**

```bash
curl -X POST -H 'Content-Type: text/yaml' --data-binary @custom-acme-baseline.yaml .../compliance/kyverno/custom-mappings
```

### List compliance standards

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

Lists every compliance standard available to the tenant: built-in standards plus the tenant's custom standards. Does not require any reports to exist.

**Roles:** `admin`, `platform`, `security`, `devops`

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

Array of ComplianceStandardDto

| Field | Type | Description |
|---|---|---|
| `standard` | `string` | Standard key |
| `standardDisplayName` | `string` | — |
| `custom` | `boolean` | True for tenant-uploaded standards |
| `type` | `string` | built-in \| industry \| custom |
| `domain` | `string[]` | Topical tags, e.g. kubernetes, identity-rbac, supply-chain |

**Errors**

- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Download an example custom standard

```http
GET /policies/api/v1/compliance/kyverno/custom-mappings/example
```

Returns a fully commented, schema-valid example custom standard YAML (custom-mapping.example.yaml) that can be edited and uploaded.

**Roles:** `admin`, `platform`, `security`, `devops`

**Response** `200` (`text/yaml`)

YAML document (attachment)

**Errors**

- `500` — Example resource unavailable
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Download the custom standard JSON Schema

```http
GET /policies/api/v1/compliance/kyverno/custom-mappings/schema
```

Returns the JSON Schema describing the YAML body accepted when creating or updating a custom compliance standard, as an attachment (custom-mapping.schema.json).

**Roles:** `admin`, `platform`, `security`, `devops`

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

JSON Schema document (attachment)

**Errors**

- `500` — Schema resource unavailable
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Get a custom compliance standard

```http
GET /policies/api/v1/compliance/kyverno/custom-mappings/{standardKey}
```

Returns one custom standard including its policy-to-control mapping and the raw uploaded YAML.

**Roles:** `admin`, `platform`, `security`, `devops`

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `standardKey` | `string` | Custom standard key |

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

Custom standard detail

| Field | Type | Description |
|---|---|---|
| `standardKey` | `string` | Unique key of the custom standard |
| `displayName` | `string` | — |
| `policyCount` | `integer` | Number of mapped policies |
| `controlCount` | `integer` | Distinct controls mapped |
| `adminState` | `string` | — |
| `createdBy` | `string` | — |
| `createdAt` | `string (date-time)` | — |
| `updatedAt` | `string (date-time)` | — |
| `preferVpol` | `boolean` | — |
| `sources` | `object[]` | {id, title, ref, effective} |
| `policies` | `object` | Map of policy name to {clusterScoped, controls} |
| `nonAutomatable` | `object[]` | {id, family, reason} |
| `rawYaml` | `string` | The uploaded YAML |
| `contentSha256` | `string` | — |

**Errors**

- `404` — No such custom standard (code NOT_FOUND)
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Update a custom compliance standard

```http
PUT /policies/api/v1/compliance/kyverno/custom-mappings/{standardKey}
```

Replaces an existing custom standard with a new YAML definition. The YAML's standardKey must match the path.

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

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `standardKey` | `string` | Custom standard key |

**Request body** (`text/yaml (also application/x-yaml, text/plain)`)

| Field | Type | Required | Description |
|---|---|---|---|
| `standardKey` | `string` | Yes | Lowercase letters, digits, hyphens; must not match a built-in standard |
| `displayName` | `string` | Yes | — |
| `preferVpol` | `boolean` | No | Informational |
| `sources` | `object[]` | No | {id, title, ref, effective} |
| `policies` | `object` | Yes | Map of Kyverno policy name to {clusterScoped, controls[]}; unknown policy names produce warnings, not errors |
| `non-automatable` | `object[]` | No | {id, family, reason} controls reported as not automatable |

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

Custom standard detail plus optional warnings

| Field | Type | Description |
|---|---|---|
| `standardKey` | `string` | Unique key of the custom standard |
| `displayName` | `string` | — |
| `policyCount` | `integer` | Number of mapped policies |
| `controlCount` | `integer` | Distinct controls mapped |
| `adminState` | `string` | — |
| `createdBy` | `string` | — |
| `createdAt` | `string (date-time)` | — |
| `updatedAt` | `string (date-time)` | — |
| `preferVpol` | `boolean` | — |
| `sources` | `object[]` | {id, title, ref, effective} |
| `policies` | `object` | Map of policy name to {clusterScoped, controls} |
| `nonAutomatable` | `object[]` | {id, family, reason} |
| `rawYaml` | `string` | The uploaded YAML |
| `contentSha256` | `string` | — |
| `warnings` | `string[]` | Present only when there are warnings |

**Errors**

- `400` — YAML fails validation or standardKey mismatch (code VALIDATION_FAILED)
- `409` — No custom standard with that key exists to update (code CONFLICT)
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Delete a custom compliance standard

```http
DELETE /policies/api/v1/compliance/kyverno/custom-mappings/{standardKey}
```

Deletes a custom standard and its standard-level enablement and target settings. Built-in standards cannot be deleted.

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

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `standardKey` | `string` | Custom standard key |

**Response** `204`

No content

**Errors**

- `404` — No such custom standard, or key is a built-in standard (code NOT_FOUND)
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### List enabled compliance standards

```http
GET /policies/api/v1/compliance/kyverno/standards/enabled
```

Lists every standard enabled for the tenant with its effective targets. Targets that no longer exist in inventory are omitted.

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

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

Array of ComplianceStandardEnablementDto

| Field | Type | Description |
|---|---|---|
| `standard` | `string` | — |
| `standardDisplayName` | `string` | — |
| `custom` | `boolean` | — |
| `type` | `string` | built-in \| industry \| custom |
| `domain` | `string[]` | — |
| `enabled` | `boolean` | Can be false in PATCH responses |
| `applyToAllTargets` | `boolean` | Applies to every target of targetTypes |
| `targetTypes` | `string[]` | cluster \| repository |
| `historyEnabled` | `boolean` | Trend history tracking enabled |
| `targets` | `object[]` | Effective live targets {targetId, targetName, targetType} |

**Errors**

- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Rescan all enabled standards

```http
POST /policies/api/v1/compliance/kyverno/standards/rescan
```

Starts on-demand scans for every enabled standard and target pair, optionally limited to some standards. Pairs that cannot start (scan already running or capacity reached) are listed in skipped; the request still returns 200.

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

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

| Field | Type | Required | Description |
|---|---|---|---|
| `standards` | `string[]` | No | Limit to these standards; omitted/empty = all enabled |

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

ComplianceRescanResponseDto

| Field | Type | Description |
|---|---|---|
| `reportIds` | `object` | Map standard -&gt; targetId -&gt; new report ID |
| `skipped` | `object[]` | {standard, targetId, code: SCAN_IN_PROGRESS \| SCAN_CAPACITY_EXCEEDED} |
| `triggeredAt` | `string (date-time)` | — |

**Errors**

- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Get a standard's control catalog

```http
GET /policies/api/v1/compliance/kyverno/standards/{standard}/controls
```

Returns every control referenced by a standard with its name, description, whether it can be checked automatically, and the Kyverno policies mapped to it. Responses carry an ETag and Cache-Control (private, max-age=300); send If-None-Match to receive 304 when unchanged.

**Roles:** `admin`, `platform`, `security`, `devops`

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `standard` | `string` | Standard key |

**Headers**

| Name | Required | Description |
|---|---|---|
| `If-None-Match` | No | ETag from a previous response; 304 if unchanged |

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

`{standard, displayName, version, controls[]}`

| Field | Type | Description |
|---|---|---|
| `standard` | `string` | — |
| `displayName` | `string` | — |
| `version` | `string` | Content hash; also the ETag |
| `controls` | `object[]` | {id, name, description, automatable, family, reason, policies[]} in natural control-ID order |

**Errors**

- `304` — Not modified (If-None-Match matched)
- `404` — Unknown standard (code STANDARD_NOT_FOUND)
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Enable a standard for targets

```http
PUT /policies/api/v1/compliance/kyverno/standards/{standard}/enablement
```

Enables a standard and replaces its target set, either an explicit list of clusters/repositories or all targets of the given types. Previously stored targets that no longer exist are dropped silently; a newly added unknown target is rejected.

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

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `standard` | `string` | Standard key |

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

| Field | Type | Required | Description |
|---|---|---|---|
| `applyToAllTargets` | `boolean` | No | Apply to every target of targetTypes |
| `targetTypes` | `string[]` | No | Required non-empty when applyToAllTargets; values cluster \| repository |
| `targets` | `object[]` | No | {targetId (uuid), targetType: cluster\|repository, targetName (ignored; server resolves)}; required unless applyToAllTargets |

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

ComplianceStandardEnablementDto

| Field | Type | Description |
|---|---|---|
| `standard` | `string` | — |
| `standardDisplayName` | `string` | — |
| `custom` | `boolean` | — |
| `type` | `string` | built-in \| industry \| custom |
| `domain` | `string[]` | — |
| `enabled` | `boolean` | Can be false in PATCH responses |
| `applyToAllTargets` | `boolean` | Applies to every target of targetTypes |
| `targetTypes` | `string[]` | cluster \| repository |
| `historyEnabled` | `boolean` | Trend history tracking enabled |
| `targets` | `object[]` | Effective live targets {targetId, targetName, targetType} |

**Errors**

- `400` — REQUEST_BODY_REQUIRED, UNKNOWN_STANDARD, TARGETS_REQUIRED, TARGET_TYPES_REQUIRED, UNSUPPORTED_TARGET_TYPE, INVALID_TARGET_ID, or UNKNOWN_TARGET
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

**Example**

```json
{"applyToAllTargets":false,"targets":[{"targetId":"3f1c...","targetType":"cluster"}]}
```

### Update standard enablement flags

```http
PATCH /policies/api/v1/compliance/kyverno/standards/{standard}/enablement
```

Toggles enabled and/or historyEnabled for a standard without changing its target set. Omitted (null) fields are left unchanged. Re-enabling restores the previous targets.

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

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `standard` | `string` | Standard key |

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

| Field | Type | Required | Description |
|---|---|---|---|
| `enabled` | `boolean` | No | Enable/disable |
| `historyEnabled` | `boolean` | No | Enable/disable history tracking |

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

ComplianceStandardEnablementDto

| Field | Type | Description |
|---|---|---|
| `standard` | `string` | — |
| `standardDisplayName` | `string` | — |
| `custom` | `boolean` | — |
| `type` | `string` | built-in \| industry \| custom |
| `domain` | `string[]` | — |
| `enabled` | `boolean` | Can be false in PATCH responses |
| `applyToAllTargets` | `boolean` | Applies to every target of targetTypes |
| `targetTypes` | `string[]` | cluster \| repository |
| `historyEnabled` | `boolean` | Trend history tracking enabled |
| `targets` | `object[]` | Effective live targets {targetId, targetName, targetType} |

**Errors**

- `400` — Body missing (REQUEST_BODY_REQUIRED)
- `404` — Standard has never been configured (code NOT_FOUND)
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Disable a compliance standard

```http
DELETE /policies/api/v1/compliance/kyverno/standards/{standard}/enablement
```

Disables a standard for the tenant. Its target set is preserved, so re-enabling restores the same targets.

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

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `standard` | `string` | Standard key |

**Response** `204`

No content

**Errors**

- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Get a standard's policy-to-control mapping

```http
GET /policies/api/v1/compliance/kyverno/standards/{standard}/mappings
```

Returns the full policy-to-control mapping of a built-in or custom standard as JSON. With format=yaml, downloads it as a custom-standard YAML file ready to edit and upload; a built-in standard's key is rewritten to custom-<standard>.

**Roles:** `admin`, `platform`, `security`, `devops`

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `standard` | `string` | Standard key |

**Query parameters**

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `format` | `string` | No | `json` | json or yaml |

**Response** `200` (`application/json (or text/yaml attachment when format=yaml)`)

ComplianceStandardMappingDto

| Field | Type | Description |
|---|---|---|
| `standard` | `string` | — |
| `displayName` | `string` | — |
| `type` | `string` | built-in \| industry \| custom |
| `custom` | `boolean` | — |
| `preferVpol` | `boolean` | — |
| `sources` | `object[]` | {id, title, ref, effective} |
| `policies` | `object[]` | {name, clusterScoped, path, controls[]} sorted by name |
| `nonAutomatable` | `object[]` | {id, family, reason} |

**Errors**

- `400` — format is not json or yaml (code INVALID_FORMAT)
- `404` — Unknown standard (code STANDARD_NOT_FOUND)
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Rescan one compliance standard

```http
POST /policies/api/v1/compliance/kyverno/standards/{standard}/rescan
```

Starts on-demand scans for every target the standard is currently enabled for. Skipped pairs are listed; returns 200 with empty results if the standard is not enabled.

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

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `standard` | `string` | Standard key |

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

ComplianceRescanResponseDto

| Field | Type | Description |
|---|---|---|
| `reportIds` | `object` | Map standard -&gt; targetId -&gt; new report ID |
| `skipped` | `object[]` | {standard, targetId, code: SCAN_IN_PROGRESS \| SCAN_CAPACITY_EXCEEDED} |
| `triggeredAt` | `string (date-time)` | — |

**Errors**

- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles