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
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.