> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orca-klavest.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports

> Generate, schedule, and share PDF reports for GDPR compliance, executive summaries, and AI readiness assessments.

## Report types

ORCA generates three types of PDF reports:

| Report type           | Description                                                                                 | Token cost                |
| --------------------- | ------------------------------------------------------------------------------------------- | ------------------------- |
| **GDPR Compliance**   | PII detection results, sensitive column inventory, compliance status, and remediation steps | 5 (basic) / 10 (advanced) |
| **Executive Summary** | High-level quality scores, issue breakdown, trend analysis, and key recommendations         | 5 (basic) / 10 (advanced) |
| **AI Readiness**      | 7-dimension readiness score, per-file breakdown, grade history, and certification status    | Free                      |

## Generating a report

### From the UI

1. Navigate to **Reports** in the sidebar.
2. Select a report type and configure options (file scope, date range).
3. Click **Generate**. The report is queued for async processing.
4. Once complete, download the PDF or share it via link.

### From the API

```bash theme={null}
curl -X POST https://api.orca-klavest.app/api/v1/reports/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "gdpr_compliance",
    "config": {}
  }'
```

The response includes a report job ID. Poll the status endpoint until `status` is `"complete"`:

```json theme={null}
{
  "data": {
    "id": "a1b2c3d4-...",
    "report_type": "gdpr_compliance",
    "status": "pending",
    "file_url": null,
    "created_at": "2026-03-31T12:00:00Z"
  }
}
```

## Downloading a report

Once the report status is `complete`, download the PDF:

```bash theme={null}
curl -L https://api.orca-klavest.app/api/v1/reports/{report_id}/download \
  -H "Authorization: Bearer $TOKEN" \
  -o report.pdf
```

The endpoint returns a `307` redirect to a time-limited S3 presigned URL. The download URL is scoped to your organisation -- cross-tenant access is blocked.

## Report scheduling

Admins can schedule recurring report generation with automatic email delivery.

| Frequency   | Delivery cadence |
| ----------- | ---------------- |
| `weekly`    | Every 7 days     |
| `monthly`   | Every 30 days    |
| `quarterly` | Every 90 days    |

### Create a schedule

```bash theme={null}
curl -X POST https://api.orca-klavest.app/api/v1/reports/schedules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "executive_summary",
    "frequency": "weekly",
    "recipients": ["cto@example.com", "data-team@example.com"],
    "config": {},
    "enabled": true
  }'
```

### Manage schedules

* **List schedules:** `GET /api/v1/reports/schedules`
* **Update a schedule:** `PATCH /api/v1/reports/schedules/{schedule_id}`
* **Delete a schedule:** `DELETE /api/v1/reports/schedules/{schedule_id}`

Schedule management requires the `admin` role.

## Public report sharing

AI Readiness reports can be shared externally via a tokenized public link. Recipients can view the report without logging in.

```
https://app.orca-klavest.app/report/{share_token}
```

The share token is unique and non-guessable. Public reports are read-only and do not expose raw data -- only scores, grades, and recommendations.

## Report verification

AI Readiness certificates include a SHA-256 verification hash. Anyone with the hash can verify that the certificate has not been tampered with by checking it against the ORCA verification endpoint:

```bash theme={null}
curl https://api.orca-klavest.app/api/v1/ai-readiness/certificates/verify \
  -H "Content-Type: application/json" \
  -d '{"verification_hash": "abc123..."}'
```

This returns the certificate details if the hash matches, confirming the report is authentic and unmodified.

## API reference

| Method   | Endpoint                               | Description                                |
| -------- | -------------------------------------- | ------------------------------------------ |
| `POST`   | `/api/v1/reports/generate`             | Create a report generation job             |
| `GET`    | `/api/v1/reports`                      | List reports (filterable by `report_type`) |
| `GET`    | `/api/v1/reports/{report_id}`          | Get report status and download URL         |
| `GET`    | `/api/v1/reports/{report_id}/download` | Download report PDF (S3 redirect)          |
| `POST`   | `/api/v1/reports/schedules`            | Create a report schedule (admin)           |
| `GET`    | `/api/v1/reports/schedules`            | List report schedules                      |
| `PATCH`  | `/api/v1/reports/schedules/{id}`       | Update a schedule (admin)                  |
| `DELETE` | `/api/v1/reports/schedules/{id}`       | Delete a schedule (admin)                  |