Reports API

See also: Reports concept and configuration for what this API powers, when to call it, and how it is configured.

All report routes live under /api/v1/reports/*, require tenant authentication, and scope every read/write to the caller’s tenant.

Authentication

Same headers as every other v1 route:

X-API-Key: krn_… plus X-Tenant-Id: <uuid>, or
a session cookie bound to a tenant-linked user account.

RBAC:

Viewer, editor, admin: all read routes + preview.
Editor, admin: create/update/delete templates, schedules; run-now.
Admin: only admin-specific routes (none here).

Templates

`GET /api/v1/reports/templates`

List tenant-scoped templates, newest first.

{
  "data": [
    {
      "id": "uuid",
      "name": "Weekly digest",
      "description": "…",
      "dataSources": [...],
      "formats": ["pdf", "csv"],
      "narrative": { "enabled": true },
      "enabled": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}

`POST /api/v1/reports/templates`

Create a template. Body:

{
  "name": "Weekly digest",
  "description": "Offer + channel roll-up",
  "dataSources": [
    { "sourceKey": "offer_performance", "params": { "days": 7 } },
    { "sourceKey": "channel_effectiveness", "params": { "days": 7 } }
  ],
  "sections": [
    { "id": "s1", "title": "Offers",   "dataSourceIndex": 0 },
    { "id": "s2", "title": "Channels", "dataSourceIndex": 1 }
  ],
  "formats": ["pdf", "csv"],
  "narrative": { "enabled": true, "prompt": "Call out retention risks." },
  "filters": { "destinations": ["<provider-uuid>"] },
  "enabled": true
}

Returns 201 with the created record.

`GET /api/v1/reports/templates/:id`

Returns 404 when not found or cross-tenant.

`PATCH /api/v1/reports/templates/:id`

Partial update. Any of the create-body fields above may be supplied.

`DELETE /api/v1/reports/templates/:id`

Returns 204. Cascade-deletes any schedules attached to the template.

`POST /api/v1/reports/templates/:id/preview`

Run the template once without dispatching or persisting. Returns the sections, narrative, and base64 artifacts inline.

{
  "sections": [
    { "id": "s1", "title": "…", "columns": [...], "rows": [...] }
  ],
  "narrative": {
    "executiveSummary": "…",
    "sectionNarratives": [{ "sectionId": "s1", "narrative": "…" }],
    "keyTakeaways": ["…"]
  },
  "artifacts": [
    { "format": "pdf", "mimeType": "application/pdf", "fileName": "weekly-digest.pdf", "base64": "…", "bytes": 23456 }
  ]
}

`POST /api/v1/reports/templates/:id/run-now`

Execute immediately with dispatch: true, persistRun: true. Returns 202 with the runId, artifact metadata, and per-destination delivery results. Synchronous for Phase 03 — long-running reports block the HTTP response.

Schedules

`GET /api/v1/reports/schedules`

List all schedules for the tenant.

`POST /api/v1/reports/schedules`

{
  "templateId": "<uuid>",
  "name": "Daily 8am",
  "cronExpression": "0 8 * * *",
  "timezone": "UTC",
  "destinations": ["<provider-uuid>"]
}

Validates the cron expression via cron-parser and computes the initial nextRunAt. Returns 404 when templateId is unknown or belongs to a different tenant. Returns 422 on invalid cron.

`GET /api/v1/reports/schedules/:id`

`PATCH /api/v1/reports/schedules/:id`

Recomputes nextRunAt when cronExpression or timezone changes.

`DELETE /api/v1/reports/schedules/:id`

Runs

`GET /api/v1/reports/runs`

Paginated run history. Query params:

templateId — filter by template
limit — 1..200, default 50
offset — default 0

Response omits artifactPayloads (base64) to keep the list JSON small.

{
  "data": [
    {
      "id": "…",
      "templateId": "…",
      "scheduleId": "…",
      "status": "completed",
      "triggeredBy": "cron",
      "startedAt": "…",
      "completedAt": "…",
      "durationMs": 4231,
      "deliveryResults": [
        { "providerId": "…", "ok": true, "providerMessageId": "…" }
      ]
    }
  ],
  "pagination": { "total": 42, "limit": 50, "offset": 0 }
}

`GET /api/v1/reports/runs/:id`

Full run record including sectionsData and narrativeOutput. Artifact list is returned as metadata only (no base64) — use the dedicated download endpoint to stream binaries.

`GET /api/v1/reports/runs/:id/artifacts/:format`

Download the rendered artifact binary for the given format. Returns the file with the correct Content-Type and a Content-Disposition: attachment; filename="…" header. 404 when the format was not rendered for the run. Supported :format values are: pdf, csv, markdown, html.

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

Authentication

Templates

`GET /api/v1/reports/templates`

`POST /api/v1/reports/templates`

`GET /api/v1/reports/templates/:id`

`PATCH /api/v1/reports/templates/:id`

`DELETE /api/v1/reports/templates/:id`

`POST /api/v1/reports/templates/:id/preview`

`POST /api/v1/reports/templates/:id/run-now`

Schedules

`GET /api/v1/reports/schedules`

`POST /api/v1/reports/schedules`

`GET /api/v1/reports/schedules/:id`

`PATCH /api/v1/reports/schedules/:id`

`DELETE /api/v1/reports/schedules/:id`

Runs

`GET /api/v1/reports/runs`

`GET /api/v1/reports/runs/:id`

`GET /api/v1/reports/runs/:id/artifacts/:format`

​Authentication

​Templates

​GET /api/v1/reports/templates

​POST /api/v1/reports/templates

​GET /api/v1/reports/templates/:id

​PATCH /api/v1/reports/templates/:id

​DELETE /api/v1/reports/templates/:id

​POST /api/v1/reports/templates/:id/preview

​POST /api/v1/reports/templates/:id/run-now

​Schedules

​GET /api/v1/reports/schedules

​POST /api/v1/reports/schedules

​GET /api/v1/reports/schedules/:id

​PATCH /api/v1/reports/schedules/:id

​DELETE /api/v1/reports/schedules/:id

​Runs

​GET /api/v1/reports/runs

​GET /api/v1/reports/runs/:id

​GET /api/v1/reports/runs/:id/artifacts/:format

Authentication

Templates

`GET /api/v1/reports/templates`

`POST /api/v1/reports/templates`

`GET /api/v1/reports/templates/:id`

`PATCH /api/v1/reports/templates/:id`

`DELETE /api/v1/reports/templates/:id`

`POST /api/v1/reports/templates/:id/preview`

`POST /api/v1/reports/templates/:id/run-now`

Schedules

`GET /api/v1/reports/schedules`

`POST /api/v1/reports/schedules`

`GET /api/v1/reports/schedules/:id`

`PATCH /api/v1/reports/schedules/:id`

`DELETE /api/v1/reports/schedules/:id`

Runs

`GET /api/v1/reports/runs`

`GET /api/v1/reports/runs/:id`

`GET /api/v1/reports/runs/:id/artifacts/:format`