Compliance Audit Reports
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 | GET | /compliance/reports/artifacts |
| Generate a compliance audit report | POST | /compliance/reports/generate |
| Get a compliance report artifact | GET | /compliance/reports/artifacts/{id} |
| Delete a compliance report artifact | DELETE | /compliance/reports/artifacts/{id} |
| Download a compliance report artifact | GET | /compliance/reports/artifacts/{id}/download |
| Generate a scheduled report now | POST | /compliance/reports/schedules/{scheduleId}/generate-now |
Reference
List compliance report artifacts
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; <=0 uses default, max 500 |
offset | integer | No | 0 | Items to skip (>=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 authenticated403— Caller’s role is not in the allowed roles
Generate a compliance audit report
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_FAILED401— Not authenticated403— Caller’s role is not in the allowed roles
Example
{"standards":["soc2","cis-eks"],"targetIds":["3f1c..."],"from":"2026-09-01T00:00:00Z","to":"2026-10-01T00:00:00Z"}
Get a compliance report artifact
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 authenticated403— Caller’s role is not in the allowed roles
Delete a compliance report artifact
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 authenticated403— Caller’s role is not in the allowed roles
Download a compliance report artifact
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 authenticated403— Caller’s role is not in the allowed roles
Generate a scheduled report now
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_FAILED401— Not authenticated403— Caller’s role is not in the allowed roles