Eden REST API
Analytics And Observability APIs
/api/v1These APIs expose fleet analytics, endpoint analytics, live streams, and telemetry exports used by operational dashboards and migration validation runs.
Route Map
Fleet Analytics
| Method | Route | Purpose |
|---|---|---|
| GET | /api/v1/analytics/status | Return analytics pipeline status. |
| GET | /api/v1/analytics/overview | Return organization analytics overview. |
| POST | /api/v1/analytics/enable | Enable analytics capture. |
| POST | /api/v1/analytics/disable | Disable analytics capture. |
| GET | /api/v1/analytics/dashboard | Return dashboard summary data. |
| GET | /api/v1/analytics/connections | Return active connection metrics. |
| GET | /api/v1/analytics/connections/stream | Stream active connection metrics. |
| GET | /api/v1/analytics/anomalies/status | Return current anomaly detector states. |
| GET | /api/v1/analytics/anomalies/transitions | Return anomaly state transitions. |
| GET | /api/v1/analytics/fleet/signals | Return fleet health signals. |
Streams And Query Capture
| Method | Route | Purpose |
|---|---|---|
| GET | /api/v1/analytics/stream | Open the main analytics SSE stream. |
| GET | /api/v1/analytics/stream/queries | Open the live query SSE stream. |
| GET | /api/v1/analytics/stream/queries/capture | Return query-capture status. |
| POST | /api/v1/analytics/stream/queries/capture | Enable capture-all query streaming. |
| DELETE | /api/v1/analytics/stream/queries/capture | Disable capture-all query streaming. |
Telemetry Export
| Method | Route | Purpose |
|---|---|---|
| GET | /api/v1/analytics/telemetry | Export telemetry rows by query parameters. |
| GET | /api/v1/analytics/telemetry/{signal} | Export one telemetry signal. |
| GET | /api/v1/analytics/clickhouse | Alias-compatible ClickHouse telemetry export. |
| GET | /api/v1/analytics/clickhouse/{signal} | Alias-compatible single-signal export. |
| GET | /api/v1/analytics/series | Return compressed columnar time-series data. |
Telemetry rows include telemetry_plane and data_class. The service binds queries to its configured private or public_marketplace plane; clients cannot request or override that isolation dimension. Series cache entries use the same plane binding. The data class is signal-owned: operational_metric, operational_log, or operational_trace.
Infrastructure Snapshots
| Method | Route | Purpose |
|---|---|---|
| GET | /api/v1/analytics/infrastructure/snapshots | List captured infrastructure snapshots. |
| GET | /api/v1/analytics/infrastructure/snapshots/stats | Return snapshot aggregate stats. |
| GET | /api/v1/analytics/infrastructure/snapshots/{snapshot_uuid} | Return a single infrastructure snapshot. |
Endpoint Analytics
| Method | Route | Purpose |
|---|---|---|
| GET | /api/v1/endpoints/{endpoint}/analytics/commands/rollups | Return command rollups. |
| GET | /api/v1/endpoints/{endpoint}/analytics/metrics | Return endpoint metric snapshots. |
| GET | /api/v1/endpoints/{endpoint}/analytics/anti-patterns | Return anti-pattern findings. |
| GET | /api/v1/endpoints/{endpoint}/analytics/blocked-commands | Return blocked command history. |
| GET | /api/v1/endpoints/{endpoint}/analytics/pii | Return PII detection findings. |
| GET | /api/v1/endpoints/{endpoint}/analytics/audit-trail | Return audit trail entries. |
| GET | /api/v1/endpoints/{endpoint}/analytics/patterns | Return discovered query patterns. |
| GET | /api/v1/endpoints/{endpoint}/analytics/users | Return per-user rollups. |
| GET | /api/v1/endpoints/{endpoint}/analytics/recommendations | Return generic endpoint recommendations. |
| GET | /api/v1/endpoints/{endpoint}/analytics/mongo/recommendations | Return MongoDB recommendations. |
| GET | /api/v1/endpoints/{endpoint}/analytics/postgres/recommendations | Return PostgreSQL recommendations. |
PostgreSQL template optimization advice
Eden does not expose a public endpoint that collects PostgreSQL execution plans, runs EXPLAIN ANALYZE, executes candidate SQL, applies a rewrite, creates an index, or changes database configuration. PostgreSQL analytics recommendations are observational only.
The internal PostgresSqlAdviceEngine can assess recorded evidence for an authorized parameterized-template revision. It accepts only bounded plan observations and abstains unless the current template/schema/statistics/server/ role/search_path/collation identity matches the evidence, all required SQL semantics are proven with independent native results, and at least three matched runtime trials in an isolated approved fixture agree. Production can contribute only non-executing EXPLAIN evidence for a read-only verified template. Cost estimates are not speedup claims; generic/custom and cold/warm plan observations remain visible for operator review.
Each submitted plan, semantic, result, and runtime artifact is bound to the exact approved revision, raw source-SQL SHA-256, and the complete candidate ID/revision/version, bind count, normalizer metadata, and raw candidate-SQL SHA-256. That raw candidate digest prevents a literal-only substitution from reusing evidence with the same normalized fingerprint. Candidate SQL must preserve the source bind count and parse as exactly one PostgreSQL SELECT; multi-statements, SELECT INTO, locking clauses, and data-modifying CTEs are rejected.
A configured template-authority Ed25519 key must verify an attestation over that exact candidate identity and its bound role, search_path, schema, statistics, server, and collation context. The attestation must resolve every candidate function under that PostgreSQL context and only immutable or stable calls may pass; volatile, mutating, and unresolved functions fail closed. These checks apply before any no-slower fixture-trial result can become measured advice.
Audit Trail Pagination And Scope
GET /api/v1/endpoints/{endpoint}/analytics/audit-trail accepts range, command, success, min_latency_us, and limit filters. limit defaults to 500 and must be between 1 and 1,000.
Pagination is a stable keyset over (event_time, event_id). Pass both cursor_time and cursor_id from the previous response's next_cursor; supplying only one is rejected. total_count covers every matching event in the requested range, not only the current page.
The query always combines the authenticated organization UUID with the endpoint UUID. A caller cannot override the tenant scope with query parameters, and the route requires the endpoint audit permission.
Notes
- Stream routes require clients to keep the HTTP connection open and handle reconnects.
- Some analytics routes require the service to be built with analytics and stream features enabled.
- Migration dashboards consume both aggregate analytics and endpoint analytics during live runs.