POST /telemetry

This endpoint accepts client-side usage statistics rollups. It enforces a strict aggregate-only whitelist to ensure no cleartext memory contents or PII can ever be sent to the database.

Session JWT Required

This endpoint requires a Supabase user session JWT.

1. Submit Telemetry Report

Push a daily rollup of numeric counters to the platform.

Request URL

POST /telemetry

Request Body Schema

The request must contain only the following whitelist fields. Extra fields are rejected immediately to protect privacy.

Field	Type	Required	Description
`memory_count`	`integer`	No	Current count of stored memories (must be $\ge 0$).
`device_count`	`integer`	No	Number of active syncing devices (must be $\ge 0$).
`bytes_stored`	`integer`	No	Total size of local database files in bytes (must be $\ge 0$).
`sync_ops`	`integer`	No	Number of synchronization actions completed in this window (must be $\ge 0$).
`window_start`	`string`	No	ISO-8601 timestamp for the start of the daily rollup window.

Example Request Body

{
  "memory_count": 1240,
  "device_count": 2,
  "bytes_stored": 8104820,
  "sync_ops": 420,
  "window_start": "2026-06-09T00:00:00.000Z"
}

Processing Gates

Opt-In Enforcement: The server retrieves the user's dashboard settings. If telemetry_opt_in is not explicitly set to true, the write is rejected with 403 telemetry_disabled.
Strict Whitelisting: If the request contains any keys outside the whitelist (e.g. memory_contents, metadata), the request is rejected with 400 non_aggregate_field.
Postgres Upsert: Statistics are upserted into the database. A unique constraint on (user_id, window_start) aggregates inputs to a single row per day.

Response Schema (201 Created)

{
  "aggregate": {
    "user_id": "0x123456789...",
    "window_start": "2026-06-09T00:00:00.000Z",
    "memory_count": 1240,
    "device_count": 2,
    "bytes_stored": 8104820,
    "sync_ops": 420,
    "reported_at": "2026-06-09T16:45:30.123Z"
  }
}