# Analytics — Umney Connect API

> For AI agents. Cloudflare-style token: service **Analytics**, permission `analytics:read`.
> **Live** public read-only REST under `/api/v1/analytics/*` for **conversion** metrics/events.
> Live Chat inbox reports (`/dashboard/chat/reports`) are a **separate** Live Chat surface — do not conflate them.
> Prefer customer-facing names. Do not expose internal billing catalog IDs.

## Quick facts

| Item | Value |
|---|---|
| Service | Analytics |
| Status | Public Analytics API **live** (read-only) |
| Permission | `analytics:read` |
| Key | `umk_live_analytics_<8>_<secret>` |
| HTML | https://umneyconnect.com/developers/analytics |
| Markdown | https://umneyconnect.com/developers/analytics.md |
| OpenAPI | https://umneyconnect.com/developers/openapi-analytics.json |
| JWT live | CRUD /api/growth/analytics/conversion-metrics\|events; GET …/statistics |
| Production API | https://umneyconnect.com/api |

## Create access

1. Enable **Analytics** in Billing.
2. Create API token with `analytics:read`.
3. Store secret server-side only.

## Public API (token — live, read-only)

| Method | Path | Permission | Status |
|---|---|---|---|
| GET | `/v1/analytics/metrics` | analytics:read | **Live** (`?active=true&limit=`) |
| GET | `/v1/analytics/metrics/{id}` | analytics:read | **Live** |
| GET | `/v1/analytics/metrics/{id}/series` | analytics:read | **Live** (`?days=30`) |
| GET | `/v1/analytics/events` | analytics:read | **Live** (`?metricId=&eventName=&from=&to=&limit=`) |
| GET | `/v1/analytics/events/{id}` | analytics:read | **Live** |
| GET | `/v1/analytics/statistics` | analytics:read | **Live** (30d aggregates) |

No public exports/async jobs — do not invent `POST /exports`. Writes stay on JWT Growth.

## Concepts

| Resource | Description |
|---|---|
| Conversion metric | Named metric keyed by `eventName` (+ optional `valueField`) |
| Event | Tracked row with `revenueCents`, `properties`, `occurredAt` |
| Series | Daily `events` + `revenueCents` buckets for one metric |
| Statistics | `conversions30d`, `revenue30dCents`, `eventTypes30d` |

## Agent checklist

1. /llms.txt → this file
2. Enable product → create `analytics:read` token
3. Use metrics/events/series — not Live Chat reports
4. Do not invent crawl or write scopes on the public API