---
title: "Compliance Audit Reports"
description: "Policies API v1 endpoints for generating and downloading compliance audit reports."
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_audit_reports/
---


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

Generate compliance audit reports across standards and targets, then list, download, and delete the generated report artifacts.

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

## Endpoints

| Operation | Method | Path |
|---|---|---|
| [List compliance report artifacts](#list-compliance-report-artifacts) | `GET` | `/compliance/reports/artifacts` |
| [Generate a compliance audit report](#generate-a-compliance-audit-report) | `POST` | `/compliance/reports/generate` |
| [Get a compliance report artifact](#get-a-compliance-report-artifact) | `GET` | `/compliance/reports/artifacts/{id}` |
| [Delete a compliance report artifact](#delete-a-compliance-report-artifact) | `DELETE` | `/compliance/reports/artifacts/{id}` |
| [Download a compliance report artifact](#download-a-compliance-report-artifact) | `GET` | `/compliance/reports/artifacts/{id}/download` |
| [Generate a scheduled report now](#generate-a-scheduled-report-now) | `POST` | `/compliance/reports/schedules/{scheduleId}/generate-now` |

## Reference

### List compliance report artifacts

```http
GET /policies/api/v1/compliance/reports/artifacts
```

Lists stored compliance report artifacts, newest first. Filters match both single-scope and composed audit reports.

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

**Query parameters**

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `targetId` | `string` | No | — | Filter by target UUID |
| `standard` | `string` | No | — | Filter by standard key |
| `scheduleId` | `string` | No | — | Filter by originating schedule |
| `source` | `string` | No | — | Filter by source: policy_hub \| compliance_standard \| audit |
| `limit` | `integer` | No | `100` | Page size; &lt;=0 uses default, max 500 |
| `offset` | `integer` | No | `0` | Items to skip (&gt;=0) |

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

Array of artifact summaries (no total count)

| Field | Type | Description |
|---|---|---|
| `id` | `string (uuid)` | Artifact ID |
| `scheduleRef` | `string` | Schedule that produced it, if any |
| `source` | `string` | policy_hub \| compliance_standard \| audit |
| `targetId` | `string (uuid)` | Single-scope artifacts only |
| `targetType` | `string` | — |
| `targetName` | `string` | — |
| `standard` | `string` | Single-scope artifacts only |
| `generatedAt` | `string (date-time)` | — |
| `triggerType` | `string` | scheduled \| on_demand |
| `score` | `number` | — |
| `level` | `string` | green \| yellow \| red \| unknown |
| `passControls` | `integer` | — |
| `failControls` | `integer` | — |
| `totalControls` | `integer` | — |
| `standards` | `string[]` | Composed audit reports |
| `targetIds` | `string[]` | Composed audit reports |
| `periodFrom` | `string (date-time)` | Composed audit reports |
| `periodTo` | `string (date-time)` | Composed audit reports |

**Errors**

- `400` — INVALID_OFFSET or INVALID_FILTER (bad targetId)
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Generate a compliance audit report

```http
POST /policies/api/v1/compliance/reports/generate
```

Generates a composed audit report covering several standards and targets over a time period and stores it as an artifact. The period defaults to the last 30 days.

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

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

| Field | Type | Required | Description |
|---|---|---|---|
| `standards` | `string[]` | Yes | Standard keys (must be known) |
| `targetIds` | `string[]` | Yes | Target UUIDs |
| `from` | `string (date-time)` | No | Period start; must be given together with to |
| `to` | `string (date-time)` | No | Period end; after from |
| `periodDays` | `integer` | No | Rolling window when from/to absent; default 30, max 10000 |

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

`{artifactId, generatedAt, score, level, sectionsWithData, sectionsWithoutData}`

| Field | Type | Description |
|---|---|---|
| `artifactId` | `string (uuid)` | — |
| `generatedAt` | `string (date-time)` | — |
| `score` | `number` | — |
| `level` | `string` | — |
| `sectionsWithData` | `integer` | Standard x target sections with scan data |
| `sectionsWithoutData` | `integer` | Sections with no data |

**Errors**

- `400` — Invalid options, e.g. unknown standard, bad target UUID, from/to mismatch, scope too large (INVALID_REPORT_CONFIG)
- `500` — GENERATE_FAILED
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

**Example**

```json
{"standards":["soc2","cis-eks"],"targetIds":["3f1c..."],"from":"2026-09-01T00:00:00Z","to":"2026-10-01T00:00:00Z"}
```

### Get a compliance report artifact

```http
GET /policies/api/v1/compliance/reports/artifacts/{id}
```

Returns an artifact's metadata plus the full report content: an nctl-format snapshot for single-scope artifacts, or the composed audit report for multi-standard reports.

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

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `id` | `string` | Artifact ID (UUID) |

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

Artifact summary fields + contentSha256 + report

| Field | Type | Description |
|---|---|---|
| `id` | `string (uuid)` | Artifact ID |
| `scheduleRef` | `string` | Schedule that produced it, if any |
| `source` | `string` | policy_hub \| compliance_standard \| audit |
| `targetId` | `string (uuid)` | Single-scope artifacts only |
| `targetType` | `string` | — |
| `targetName` | `string` | — |
| `standard` | `string` | Single-scope artifacts only |
| `generatedAt` | `string (date-time)` | — |
| `triggerType` | `string` | scheduled \| on_demand |
| `score` | `number` | — |
| `level` | `string` | green \| yellow \| red \| unknown |
| `passControls` | `integer` | — |
| `failControls` | `integer` | — |
| `totalControls` | `integer` | — |
| `standards` | `string[]` | Composed audit reports |
| `targetIds` | `string[]` | Composed audit reports |
| `periodFrom` | `string (date-time)` | Composed audit reports |
| `periodTo` | `string (date-time)` | Composed audit reports |
| `contentSha256` | `string` | Hash of stored report content |
| `report` | `object` | Snapshot or composed audit report |

**Errors**

- `404` — Artifact not found or id malformed (ARTIFACT_NOT_FOUND)
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Delete a compliance report artifact

```http
DELETE /policies/api/v1/compliance/reports/artifacts/{id}
```

Permanently deletes a stored report artifact.

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

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `id` | `string` | Artifact ID (UUID) |

**Response** `204`

No content

**Errors**

- `404` — Artifact not found or id malformed (ARTIFACT_NOT_FOUND)
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Download a compliance report artifact

```http
GET /policies/api/v1/compliance/reports/artifacts/{id}/download
```

Downloads an artifact as a JSON, CSV, or PDF attachment. PDF is available only for composed audit reports and is cached after the first render.

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

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `id` | `string` | Artifact ID (UUID) |

**Query parameters**

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `format` | `string` | No | `json` | json \| csv \| pdf |

**Response** `200` (`application/json | text/csv | application/pdf`)

`File attachment (compliance-report-<scope>-<id>.<ext>)`

**Errors**

- `400` — Unsupported format (UNSUPPORTED_FORMAT)
- `404` — Artifact not found (ARTIFACT_NOT_FOUND) or PDF requested for a non-audit artifact (PDF_NOT_AVAILABLE)
- `500` — PDF rendering failed (PDF_RENDER_FAILED)
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles

### Generate a scheduled report now

```http
POST /policies/api/v1/compliance/reports/schedules/{scheduleId}/generate-now
```

Immediately generates a report artifact using a compliance report schedule's saved configuration (compliance history, compliance standard history, or audit report types). The run is recorded as on-demand but attributed to the schedule.

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

**Path parameters**

| Name | Type | Description |
|---|---|---|
| `scheduleId` | `string` | Report schedule ID |

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

`{artifactId, generatedAt, score}`

| Field | Type | Description |
|---|---|---|
| `artifactId` | `string (uuid)` | — |
| `generatedAt` | `string (date-time)` | — |
| `score` | `number` | — |

**Errors**

- `400` — Schedule is not a compliance report schedule (NOT_A_COMPLIANCE_HISTORY_SCHEDULE) or its config is invalid (INVALID_REPORT_CONFIG)
- `404` — Schedule not found (SCHEDULE_NOT_FOUND)
- `409` — Report already exists for the period (DUPLICATE_PERIOD)
- `500` — GENERATE_FAILED
- `401` — Not authenticated
- `403` — Caller's role is not in the allowed roles