Analytics API

REST endpoints for the Analytics module — dashboards, reports, KPIs, goals, custom metrics.

Endpoints

Method	Path	Purpose
GET	`/api/analytics/overview`	Tenant-wide KPI roll-up.
GET	`/api/analytics/overview/comparison`	Period-over-period deltas.
GET	`/api/analytics/funnel`	Sales funnel breakdown.
GET	`/api/analytics/insights`	LLM-generated explanations of recent metric movement.
GET	`/api/analytics/anomalies`	Detected anomalies (z-score over rolling window).
GET	`/api/analytics/dashboards`	List custom dashboards.
POST	`/api/analytics/dashboards`	Create a dashboard.
GET/PATCH/DELETE	`/api/analytics/dashboards/{id}`	CRUD.
GET	`/api/analytics/dashboards/{id}/widgets`	List widgets in a dashboard.
POST	`/api/analytics/dashboards/{id}/share`	Generate a public share token.
GET	`/api/analytics/dashboards/public/{token}`	Public read-only access (token-gated).
GET	`/api/analytics/reports`	List saved reports.
POST	`/api/analytics/reports`	Create a report definition (config + schedule).
GET/PATCH/DELETE	`/api/analytics/reports/{id}`	CRUD.
POST	`/api/analytics/reports/export`	One-shot export (csv/json/pdf) without saving.
POST	`/api/analytics/reports/schedule`	Set or update a report's email schedule.
GET	`/api/analytics/goals`	List KPI goals.
POST	`/api/analytics/goals`	Create.
GET	`/api/analytics/custom-metrics`	List custom metric definitions.
POST	`/api/analytics/custom-metrics`	Create.
POST	`/api/analytics/alerts/check`	Run alert evaluation (internal, used by cron).

Key entity shapes

Report

{
  "id": "uuid",
  "name": "string",
  "report_type": "performance | content | social | seo | custom",
  "config": {
    "metrics": ["string"],
    "dimensions": ["string"],
    "filters": { },
    "period": "last_7_days | last_30_days | last_90_days | …",
    "visualization": "table | bar | line | pie"
  },
  "schedule": {
    "enabled": true,
    "frequency": "daily | weekly | monthly",
    "recipients": ["email"],
    "format": "csv | json | pdf"
  }
}

Permissions

Seeded slugs: analytics.dashboard.read, analytics.reports.read|create|export. Dashboards / goals / custom-metrics endpoints gate on those overlays — there are no separate seeded analytics.goals.* or analytics.custom_metrics.* slugs. The reports/schedule endpoint requires analytics.reports.create (creating/updating the schedule is the same RBAC bucket as creating a report definition).

Events

The analytics module does not publish to the platform event bus today. Report runs, goal hits, and anomaly detections surface in the in-app activity feed but are not emitted as webhook events.

Scheduled exports

analytics-scheduled-exports cron walks analytics_reports rows with schedule.enabled=true whose last_run_at is older than the frequency window, and enqueues a generate-report worker job per due row. The worker writes the artifact to the reports storage bucket and emails the signed URL to schedule.recipients. PDF format renders printable HTML (user prints-to-PDF).

OpenAPI

Full schema at /api/openapi.json.