# DataGauge

> A programmable metrics API and portfolio dashboard for developers running
> multiple apps. POST events from any stack with one HTTP call and get MAU,
> signups, revenue, and MRR per app, plus a portfolio rollup — then read the
> same numbers back over HTTP for your pricing page, admin panel, or investor
> update. Deliberately not another analytics tool: no funnels, no session
> replay — just the numbers you check, kept accurate (a webhook that fires
> twice can't double revenue; a retried event can't inflate user counts).

## API

Authentication is `Authorization: Bearer <key>` on every request. There are
three planes and two credential classes.

Data plane — app-scoped keys. Server keys (`sk_live_`) can write and read
everything; publishable keys (`pk_live_`) may only send behavioral events and
can never touch money or read metrics.

- Write (ingest plane, `https://in.datagauge.dev`): `POST /v1/events` for
  append-only events (single object or array), `POST /v1/objects` for mutable
  subscription state (the source of MRR).
- Read (query plane, `https://api.datagauge.dev`): `GET /v1/metrics/{metric}`
  where metric is one of mau, dau, signups, revenue, mrr, volume, and more,
  over any `date_from`/`date_to` window.

Control plane — org-scoped `dg_live_` tokens, a separate credential class that
ingest and query do not accept (and vice versa). It manages apps and their keys
so the whole loop can run headlessly (`https://api.datagauge.dev`):

- `POST /v1/apps`, `GET /v1/apps`, `GET|PATCH|DELETE /v1/apps/{app_id}` —
  `DELETE` archives (soft: keys revoked, history kept, plan slot freed);
  `PATCH {"archived": false}` restores.
- `POST|GET /v1/apps/{app_id}/keys`, `DELETE /v1/apps/{app_id}/keys/{key_id}`
- `PUT /v1/apps/{app_id}/webhooks/{provider}` — write-only; there is no read path
  for a signing secret.

Tokens carry an explicit scope set chosen at mint time (`apps:read`,
`apps:write`, `keys:read`, `keys:write`, `webhooks:write`) and scopes never
imply one another. Two things to get right:

1. `POST /v1/apps` returns `sk_key` and `POST /v1/apps/{app_id}/keys` returns
   `key` **exactly once**. Nothing can retrieve that material again — reads are
   masked. Persist it on receipt.
2. Anything not visible to your token is `404`, never `403` — an app in another
   org is deliberately indistinguishable from one that does not exist, so a
   `403` can never confirm that an id is real.

```sh
# Send an event
curl -X POST https://in.datagauge.dev/v1/events \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"user_signup","user":"usr_8813"}'

# Read a number back
curl "https://api.datagauge.dev/v1/metrics/mrr" \
  -H "Authorization: Bearer sk_live_..."

# Create an app headlessly — the sk_key in the response is shown once
curl -X POST https://api.datagauge.dev/v1/apps \
  -H "Authorization: Bearer dg_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"My App"}'
```

MCP — an agent can skip curl entirely. A read-only [MCP](https://modelcontextprotocol.io)
server at `https://mcp.datagauge.dev/mcp` exposes `portfolio.summary` (the whole
org's rollup in one call), `apps.list`, and `metrics.get` as tools; authenticate
with a `dg_live_` token carrying `metrics:read` + `apps:read`. It can read numbers
but cannot write, mint, or mutate anything.

Machine-readable spec: [OpenAPI 3.1](https://datagauge.dev/openapi.json)

## Docs

- [Quickstart](https://datagauge.dev/docs/quickstart.md): Integrate DataGauge from a bash script, no dependency, in under 5 minutes. Send your first event, read your numbers back, and rehearse in test mode before going live.
- [Overview](https://datagauge.dev/docs/sdks.md): For most stacks the curl example is the SDK. SDKs exist only where a runtime actively fights the simple fire-and-forget path, one per execution model.
- [@datagauge/edge](https://datagauge.dev/docs/sdks/edge.md): DataGauge for serverless & edge runtimes: event sends ride the platform's waitUntil so they survive the response.
- [@datagauge/convex](https://datagauge.dev/docs/sdks/convex.md): DataGauge for Convex. track() schedules a registered internalAction transactionally with your mutation: rollback sends nothing, commit guarantees the send.
- [@datagauge/client](https://datagauge.dev/docs/sdks/client.md): DataGauge for client & offline runtimes: a durable queue with pluggable storage, idempotent replay, and server-side clock-skew correction. Ship a public key.
- [@datagauge/node](https://datagauge.dev/docs/sdks/node.md): DataGauge for short-lived processes: a synchronous buffer with one explicit flush before exit. No timers, no daemon threads, no surprises.
- [POST /v1/events](https://datagauge.dev/docs/api/events.md): Append-only event ingestion: one object or an array, idempotency, timestamp skew correction, and the exact-money payment path.
- [POST /v1/objects](https://datagauge.dev/docs/api/objects.md): Mutable subscription state, upserted with last-write-wins semantics. The source of MRR.
- [GET /v1/metrics/*](https://datagauge.dev/docs/api/metrics.md): The read API: the same numbers the dashboard shows, for your own pricing pages, admin panels, and investor updates.
- [Billing webhooks](https://datagauge.dev/docs/api/webhooks.md): MRR and revenue with zero product code: paste your Stripe or Polar signing secret and point the biller at your endpoint.
- [Control API](https://datagauge.dev/docs/api/apps.md): Create apps, mint and revoke keys, set webhook secrets over HTTP, so an agent can run the whole loop without touching the dashboard.
- [MCP server](https://datagauge.dev/docs/api/mcp.md): Point Claude, Cursor, or any MCP client at mcp.datagauge.dev and let an agent read your numbers directly. Read-only, no install, always current.
- [Keys & scoping](https://datagauge.dev/docs/concepts/keys.md): Two kinds of key, one hard rule: money is server-authoritative. Public keys ship in binaries and can never write revenue. Plus test mode: sk_test_/pk_test_ keys and dg_test_ tokens run in a fully isolated test environment.
- [Why the numbers are right](https://datagauge.dev/docs/concepts/trust.md): The only thing a metrics product sells is trust in the numbers. Here is what that means mechanically.

## Optional

- [All docs concatenated](https://datagauge.dev/llms-full.txt)