Quick Start

Snapshots is push-only: you POST a full, typed payload to a widget and it's stored as a new immutable version. This guide pushes your first one.

1. Create a widget

In your org, go to Widgets → Create, pick a type (say kpi), and open it. The widget page shows its ID and a ready-to-run push snippet. You'll need the ID below.

2. Create an API key

Go to Settings → API Keys → Create and choose the Push Only preset. Copy the secret — it's shown once. See Authentication for what the presets grant.

3. Push a snapshot

Send data matching the widget's type schema. as_of is optional (the business time the data describes; defaults to now).

curl

curl -X POST https://snapshots.finopsbricks.com/api/v1/widgets/WIDGET_ID/snapshots \
  -H "api-key: <KEY>" -H "api-secret: <SECRET>" \
  -H "Content-Type: application/json" \
  -d '{
    "as_of": "2026-01-31T00:00:00Z",
    "data": { "value": 145000, "label": "MRR", "unit": "$", "delta": 12000 }
  }'

Python

import requests

requests.post(
    "https://snapshots.finopsbricks.com/api/v1/widgets/WIDGET_ID/snapshots",
    headers={"api-key": "<KEY>", "api-secret": "<SECRET>"},
    json={
        "as_of": "2026-01-31T00:00:00Z",
        "data": {"value": 145000, "label": "MRR", "unit": "$", "delta": 12000},
    },
).raise_for_status()

Node

await fetch(
  "https://snapshots.finopsbricks.com/api/v1/widgets/WIDGET_ID/snapshots",
  {
    method: "POST",
    headers: {
      "api-key": "<KEY>",
      "api-secret": "<SECRET>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      as_of: "2026-01-31T00:00:00Z",
      data: { value: 145000, label: "MRR", unit: "$", delta: 12000 },
    }),
  },
);

A 201 means it's stored. Open the widget — it renders the latest version with a freshness stamp.

4. Push again

Run it again with new numbers. Each push is a new version; the dashboard's scrubber walks back through them. That's the whole model — see Snapshots for versioning, as_of vs received_at, and reading history.