---
title: "Policy Exception Requests"
description: "Policies API v1 endpoints for reading policy exception requests."
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_exception_requests/
---


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

Read policy exception requests submitted for approval. The v1 API currently provides read access only. Create, approve, and reject exception requests from the Nirmata Control Hub console.

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

## Endpoints

| Operation | Method | Path |
|---|---|---|
| [List policy exception requests](#list-policy-exception-requests) | `GET` | `/policy-exception-requests` |
| [Count policy exception requests](#count-policy-exception-requests) | `GET` | `/policy-exception-requests/count` |
| [List pending exception requests](#list-pending-exception-requests) | `GET` | `/policy-exception-requests/pending` |
| [Get a policy exception request](#get-a-policy-exception-request) | `GET` | `/policy-exception-requests/{id}` |
| [List exception requests for a cluster](#list-exception-requests-for-a-cluster) | `GET` | `/policy-exception-requests/by-cluster/{clusterId}` |
| [List exception requests by requester](#list-exception-requests-by-requester) | `GET` | `/policy-exception-requests/by-requester/{requestedBy}` |
| [List exception requests by state](#list-exception-requests-by-state) | `GET` | `/policy-exception-requests/by-status/{status}` |

## Reference

### List policy exception requests

```http
GET /policies/api/v1/policy-exception-requests
```

Returns all policy exception requests 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: PolicyExceptionRequest[], total, limit, offset}`

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Request ID |
| `name` | `string` | Request name |
| `requestedBy` | `string` | User who submitted the request |
| `requestedByEmail` | `string` | Email of the requester |
| `status` | `string` | Request state: pendingApproval \| approved \| rejected |
| `requestType` | `string` | Type of exception request |
| `justification` | `string` | Reason given by the requester |

**Errors**

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

### Count policy exception requests

```http
GET /policies/api/v1/policy-exception-requests/count
```

Returns the total number of policy exception requests in the tenant.

**Roles:** `admin`

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

`{count: integer}`

| Field | Type | Description |
|---|---|---|
| `count` | `integer` | Number of requests |

**Errors**

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

### List pending exception requests

```http
GET /policies/api/v1/policy-exception-requests/pending
```

Returns all requests awaiting approval (state pendingApproval). Not paginated.

**Roles:** `admin`

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

`PolicyExceptionRequest[] (plain array)`

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Request ID |
| `name` | `string` | Request name |
| `requestedBy` | `string` | User who submitted the request |
| `requestedByEmail` | `string` | Email of the requester |
| `status` | `string` | Request state: pendingApproval \| approved \| rejected |
| `requestType` | `string` | Type of exception request |
| `justification` | `string` | Reason given by the requester |

**Errors**

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

### Get a policy exception request

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

Returns a single policy exception request by ID.

**Roles:** `admin`

**Path parameters**

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

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

PolicyExceptionRequest

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Request ID |
| `name` | `string` | Request name |
| `requestedBy` | `string` | User who submitted the request |
| `requestedByEmail` | `string` | Email of the requester |
| `status` | `string` | Request state: pendingApproval \| approved \| rejected |
| `requestType` | `string` | Type of exception request |
| `justification` | `string` | Reason given by the requester |

**Errors**

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

### List exception requests for a cluster

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

Returns requests that target the given cluster. Not paginated.

**Roles:** `admin`

**Path parameters**

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

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

`PolicyExceptionRequest[] (plain array)`

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Request ID |
| `name` | `string` | Request name |
| `requestedBy` | `string` | User who submitted the request |
| `requestedByEmail` | `string` | Email of the requester |
| `status` | `string` | Request state: pendingApproval \| approved \| rejected |
| `requestType` | `string` | Type of exception request |
| `justification` | `string` | Reason given by the requester |

**Errors**

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

### List exception requests by requester

```http
GET /policies/api/v1/policy-exception-requests/by-requester/{requestedBy}
```

Returns requests submitted by the given user. Not paginated.

**Roles:** `admin`

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `requestedBy` | `string` | Requester identifier, matched exactly against the stored requestedBy value |

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

`PolicyExceptionRequest[] (plain array)`

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Request ID |
| `name` | `string` | Request name |
| `requestedBy` | `string` | User who submitted the request |
| `requestedByEmail` | `string` | Email of the requester |
| `status` | `string` | Request state: pendingApproval \| approved \| rejected |
| `requestType` | `string` | Type of exception request |
| `justification` | `string` | Reason given by the requester |

**Errors**

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

### List exception requests by state

```http
GET /policies/api/v1/policy-exception-requests/by-status/{status}
```

Returns requests whose state exactly matches the given value. Not paginated.

**Roles:** `admin`

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `status` | `string` | Request state: pendingApproval, approved or rejected (case-sensitive) |

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

`PolicyExceptionRequest[] (plain array)`

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Request ID |
| `name` | `string` | Request name |
| `requestedBy` | `string` | User who submitted the request |
| `requestedByEmail` | `string` | Email of the requester |
| `status` | `string` | Request state: pendingApproval \| approved \| rejected |
| `requestType` | `string` | Type of exception request |
| `justification` | `string` | Reason given by the requester |

**Errors**

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