---
title: "Policy Exceptions"
description: "Policies API v1 endpoints for reading Kyverno policy exceptions."
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/policy_exceptions/
---


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

Read the Kyverno policy exceptions that Nirmata Control Hub tracks across your clusters, and the resources each exception covers.

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

## Endpoints

| Operation | Method | Path |
|---|---|---|
| [List policy exceptions](#list-policy-exceptions) | `GET` | `/policy-exceptions` |
| [Count policy exceptions](#count-policy-exceptions) | `GET` | `/policy-exceptions/count` |
| [Find policy exceptions for a policy on a cluster](#find-policy-exceptions-for-a-policy-on-a-cluster) | `GET` | `/policy-exceptions/search` |
| [Get policy exception summary](#get-policy-exception-summary) | `GET` | `/policy-exceptions/summary` |
| [Get a policy exception](#get-a-policy-exception) | `GET` | `/policy-exceptions/{id}` |
| [List policy exceptions for a cluster](#list-policy-exceptions-for-a-cluster) | `GET` | `/policy-exceptions/by-cluster/{clusterId}` |
| [List policy exceptions by kind](#list-policy-exceptions-by-kind) | `GET` | `/policy-exceptions/by-kind/{kind}` |
| [List policy exceptions in a namespace](#list-policy-exceptions-in-a-namespace) | `GET` | `/policy-exceptions/by-namespace/{namespace}` |
| [List resources excepted by a policy exception](#list-resources-excepted-by-a-policy-exception) | `GET` | `/policy-exceptions/{id}/excepted-resources` |

## Reference

### List policy exceptions

```http
GET /policies/api/v1/policy-exceptions
```

Returns all Kyverno policy exceptions in the tenant, paginated in memory with limit/offset.

**Roles:** `admin`

**Query parameters**

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `limit` | `integer` | No | `50` | Maximum items to return |
| `offset` | `integer` | No | `0` | Number of items to skip |

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

`Paginated: {items: PolicyException[], total, limit, offset}`

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Policy exception ID |
| `apiVersion` | `string` | Kyverno API version of the PolicyException resource |
| `kind` | `string` | Resource kind (e.g. PolicyException) |
| `name` | `string` | Policy exception name |
| `namespace` | `string` | Kubernetes namespace of the exception |
| `uid` | `string` | Kubernetes UID |
| `resourceVersion` | `string` | Kubernetes resource version |
| `clusterRef` | `object` | Reference to the cluster: {service, modelIndex, id} |
| `exceptions` | `array<object>` | Excepted policies/rules: {policyName, ruleNames, namespace, policyUID, kind, policyRef} |
| `exceptedResources` | `array<object>` | Resources currently excepted: {apiVersion, kind, name, namespace, fieldPath, resourceVersion, uid, resourceRef} |
| `yaml` | `string` | Full YAML of the PolicyException resource |
| `requestDetails` | `string` | JSON-encoded string with details of the originating exception request, if any |

**Errors**

- `500` — Failed to retrieve policy exceptions
- `401` — Missing or invalid credentials
- `403` — Caller's role is not permitted

### Count policy exceptions

```http
GET /policies/api/v1/policy-exceptions/count
```

Returns the total number of policy exceptions in the tenant.

**Roles:** `admin`

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

`{count: integer}`

| Field | Type | Description |
|---|---|---|
| `count` | `integer` | Number of policy exceptions |

**Errors**

- `500` — Failed to count policy exceptions
- `401` — Missing or invalid credentials
- `403` — Caller's role is not permitted

### Find policy exceptions for a policy on a cluster

```http
GET /policies/api/v1/policy-exceptions/search
```

Returns lightweight records of policy exceptions on a cluster that except the named policy, optionally restricted to a namespace.

**Roles:** Any role with permission for this resource. See [Roles](../#roles).

**Query parameters**

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `clusterId` | `string` | Yes | — | Cluster ID |
| `policy` | `string` | Yes | — | Exact policy name to match in the exception's policy list |
| `namespace` | `string` | No | — | Restrict to exceptions in this namespace |

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

`Array of {id, name, namespace}`

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Policy exception ID |
| `name` | `string` | Name (empty string if unset) |
| `namespace` | `string` | Namespace (empty string if unset) |

**Errors**

- `400` — clusterId or policy query parameter missing
- `500` — Failed to search policy exceptions
- `401` — Missing or invalid credentials
- `403` — Caller's role is not permitted

**Example**

```bash
curl -H 'Authorization: NIRMATA-API <token>' 'https://<host>/policies/api/v1/policy-exceptions/search?clusterId=<id>&policy=disallow-privileged-containers'
```

### Get policy exception summary

```http
GET /policies/api/v1/policy-exceptions/summary
```

Returns counts of policy exceptions in the tenant: total, those with excepted resources, those listing policies, and empty ones.

**Roles:** Any role with permission for this resource. See [Roles](../#roles).

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

`{total, withExceptedResources, withPolicyExceptions, empty}`

| Field | Type | Description |
|---|---|---|
| `total` | `integer` | Total policy exceptions |
| `withExceptedResources` | `integer` | Exceptions that currently match at least one resource |
| `withPolicyExceptions` | `integer` | Exceptions that list at least one policy |
| `empty` | `integer` | Approximate count of exceptions without policies/resources |

**Errors**

- `500` — Failed to get policy exceptions summary
- `401` — Missing or invalid credentials
- `403` — Caller's role is not permitted

### Get a policy exception

```http
GET /policies/api/v1/policy-exceptions/{id}
```

Returns a single policy exception by ID. Users with own-scope access can only read exceptions they requested.

**Roles:** Any role with permission for this resource. See [Roles](../#roles).

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `id` | `string` | Policy exception ID |

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

PolicyException

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Policy exception ID |
| `apiVersion` | `string` | Kyverno API version of the PolicyException resource |
| `kind` | `string` | Resource kind (e.g. PolicyException) |
| `name` | `string` | Policy exception name |
| `namespace` | `string` | Kubernetes namespace of the exception |
| `uid` | `string` | Kubernetes UID |
| `resourceVersion` | `string` | Kubernetes resource version |
| `clusterRef` | `object` | Reference to the cluster: {service, modelIndex, id} |
| `exceptions` | `array<object>` | Excepted policies/rules: {policyName, ruleNames, namespace, policyUID, kind, policyRef} |
| `exceptedResources` | `array<object>` | Resources currently excepted: {apiVersion, kind, name, namespace, fieldPath, resourceVersion, uid, resourceRef} |
| `yaml` | `string` | Full YAML of the PolicyException resource |
| `requestDetails` | `string` | JSON-encoded string with details of the originating exception request, if any |

**Errors**

- `404` — Policy exception not found
- `500` — Failed to retrieve policy exception
- `401` — Missing or invalid credentials
- `403` — Caller's role is not permitted

### List policy exceptions for a cluster

```http
GET /policies/api/v1/policy-exceptions/by-cluster/{clusterId}
```

Returns all policy exceptions belonging to the given cluster. Not paginated.

**Roles:** Any role with permission for this resource. See [Roles](../#roles).

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `clusterId` | `string` | Cluster ID |

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

`PolicyException[] (plain array)`

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Policy exception ID |
| `apiVersion` | `string` | Kyverno API version of the PolicyException resource |
| `kind` | `string` | Resource kind (e.g. PolicyException) |
| `name` | `string` | Policy exception name |
| `namespace` | `string` | Kubernetes namespace of the exception |
| `uid` | `string` | Kubernetes UID |
| `resourceVersion` | `string` | Kubernetes resource version |
| `clusterRef` | `object` | Reference to the cluster: {service, modelIndex, id} |
| `exceptions` | `array<object>` | Excepted policies/rules: {policyName, ruleNames, namespace, policyUID, kind, policyRef} |
| `exceptedResources` | `array<object>` | Resources currently excepted: {apiVersion, kind, name, namespace, fieldPath, resourceVersion, uid, resourceRef} |
| `yaml` | `string` | Full YAML of the PolicyException resource |
| `requestDetails` | `string` | JSON-encoded string with details of the originating exception request, if any |

**Errors**

- `500` — Lookup failed
- `401` — Missing or invalid credentials
- `403` — Caller's role is not permitted

### List policy exceptions by kind

```http
GET /policies/api/v1/policy-exceptions/by-kind/{kind}
```

Returns all policy exceptions whose resource kind exactly matches the given value (e.g. PolicyException). Not paginated.

**Roles:** Any role with permission for this resource. See [Roles](../#roles).

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `kind` | `string` | Resource kind |

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

`PolicyException[] (plain array)`

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Policy exception ID |
| `apiVersion` | `string` | Kyverno API version of the PolicyException resource |
| `kind` | `string` | Resource kind (e.g. PolicyException) |
| `name` | `string` | Policy exception name |
| `namespace` | `string` | Kubernetes namespace of the exception |
| `uid` | `string` | Kubernetes UID |
| `resourceVersion` | `string` | Kubernetes resource version |
| `clusterRef` | `object` | Reference to the cluster: {service, modelIndex, id} |
| `exceptions` | `array<object>` | Excepted policies/rules: {policyName, ruleNames, namespace, policyUID, kind, policyRef} |
| `exceptedResources` | `array<object>` | Resources currently excepted: {apiVersion, kind, name, namespace, fieldPath, resourceVersion, uid, resourceRef} |
| `yaml` | `string` | Full YAML of the PolicyException resource |
| `requestDetails` | `string` | JSON-encoded string with details of the originating exception request, if any |

**Errors**

- `500` — Lookup failed
- `401` — Missing or invalid credentials
- `403` — Caller's role is not permitted

### List policy exceptions in a namespace

```http
GET /policies/api/v1/policy-exceptions/by-namespace/{namespace}
```

Returns all policy exceptions whose namespace exactly matches the given value. Not paginated.

**Roles:** Any role with permission for this resource. See [Roles](../#roles).

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `namespace` | `string` | Kubernetes namespace name |

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

`PolicyException[] (plain array)`

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Policy exception ID |
| `apiVersion` | `string` | Kyverno API version of the PolicyException resource |
| `kind` | `string` | Resource kind (e.g. PolicyException) |
| `name` | `string` | Policy exception name |
| `namespace` | `string` | Kubernetes namespace of the exception |
| `uid` | `string` | Kubernetes UID |
| `resourceVersion` | `string` | Kubernetes resource version |
| `clusterRef` | `object` | Reference to the cluster: {service, modelIndex, id} |
| `exceptions` | `array<object>` | Excepted policies/rules: {policyName, ruleNames, namespace, policyUID, kind, policyRef} |
| `exceptedResources` | `array<object>` | Resources currently excepted: {apiVersion, kind, name, namespace, fieldPath, resourceVersion, uid, resourceRef} |
| `yaml` | `string` | Full YAML of the PolicyException resource |
| `requestDetails` | `string` | JSON-encoded string with details of the originating exception request, if any |

**Errors**

- `500` — Lookup failed
- `401` — Missing or invalid credentials
- `403` — Caller's role is not permitted

### List resources excepted by a policy exception

```http
GET /policies/api/v1/policy-exceptions/{id}/excepted-resources
```

Returns the Kubernetes resources currently matched (excepted) by the given policy exception.

**Roles:** Any role with permission for this resource. See [Roles](../#roles).

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `id` | `string` | Policy exception ID |

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

`{exceptedResources: object[], count: integer}`

| Field | Type | Description |
|---|---|---|
| `exceptedResources` | `array<object>` | {apiVersion, kind, name, namespace, fieldPath, resourceVersion, uid, resourceRef} |
| `count` | `integer` | Number of excepted resources |

**Errors**

- `404` — Policy exception not found
- `500` — Failed to get excepted resources
- `401` — Missing or invalid credentials
- `403` — Caller's role is not permitted