Reports API

Generate, list, and download governance reports. Export audit trails in PDF or CSV format for compliance reviews, incident investigations, and executive summaries.

Endpoints

GET /reports

List all previously generated reports for the current tenant.

Headers

Header	Value
Authorization	Bearer <api_key>

Query Parameters

Parameter	Type	Default	Description
type	string	--	Filter by report type
limit	number	20	Number of results per page
offset	number	0	Pagination offset

Response

{
  "reports": [
    {
      "id": "rpt_a1b2c3d4",
      "type": "governance_summary",
      "format": "pdf",
      "status": "completed",
      "date_range": {
        "start": "2026-03-01T00:00:00Z",
        "end": "2026-03-31T23:59:59Z"
      },
      "created_at": "2026-04-01T09:15:00Z",
      "download_url": "/reports/rpt_a1b2c3d4"
    }
  ],
  "total": 12,
  "limit": 20,
  "offset": 0
}

---

POST /reports/generate

Generate a new report. Report generation runs asynchronously; poll the report status via GET /reports/:id until status is completed.

Request Body

{
  "type": "governance_summary",
  "date_range": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "format": "pdf"
}

Field	Type	Required	Description
type	string	Yes	Report type (see table below)
date_range	object	Yes	Object with start and end ISO 8601 timestamps
format	string	No	Output format: pdf (default) or csv

Response

{
  "id": "rpt_e5f6g7h8",
  "type": "governance_summary",
  "status": "generating",
  "estimated_seconds": 30,
  "created_at": "2026-04-01T09:20:00Z"
}

TIP

Most reports complete within 30 seconds. Complex reports spanning large date ranges may take up to 2 minutes.

---

GET /reports/:id

Download a completed report or check status of a generating report.

Path Parameters

Parameter	Type	Description
id	string	Report identifier (e.g., rpt_a1b2c3d4)

Response (Generating)

{
  "id": "rpt_e5f6g7h8",
  "type": "governance_summary",
  "status": "generating",
  "progress": 65
}

Response (Completed)

Returns the report file with appropriate Content-Type header (application/pdf or text/csv).

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="governance_summary_2026-03.pdf"

---

GET /audit/export

Export the full audit trail in PDF or CSV format.

Query Parameters

Parameter	Type	Required	Description
format	string	Yes	Export format: pdf or csv
start	string	No	Start date (ISO 8601). Defaults to 30 days ago.
end	string	No	End date (ISO 8601). Defaults to now.
agent_id	string	No	Filter by specific agent
verdict	string	No	Filter by verdict: CLEARED, HELD, or BLOCKED

Example -- PDF Export

curl -H "Authorization: Bearer $WARDN_API_KEY" \
  "https://api.thewardn.ai/audit/export?format=pdf&start=2026-03-01T00:00:00Z"

Example -- CSV Export

curl -H "Authorization: Bearer $WARDN_API_KEY" \
  "https://api.thewardn.ai/audit/export?format=csv&verdict=BLOCKED" \
  -o blocked_actions.csv

WARNING

Audit exports include all governed actions within the date range. Large tenants with high action volumes should use narrow date ranges to avoid timeouts.

---

Report Types

Type	Description	Contents
governance_summary	Monthly governance overview	Total actions, verdict breakdown, top policies triggered, compliance score trend
violation_report	Detailed violation analysis	All BLOCKED and HELD actions with timestamps, agent, policy, and action payload
compliance_audit	Compliance pack adherence	Per-pack policy evaluation results, gaps, recommendations
agent_activity	Per-agent activity report	Actions per agent, verdict distribution, most-triggered policies, risk trend

---

Error Responses

Status	Code	Description
400	INVALID_TYPE	Unknown report type
400	INVALID_DATE_RANGE	Start date is after end date, or range exceeds 1 year
404	REPORT_NOT_FOUND	Report ID does not exist
409	REPORT_GENERATING	Report is still being generated (retry later)