API reference

Send events to ingest and read metrics from the query API.

dumbledor has two public REST APIs. The ingest API accepts events from the browser tracker or your backend. The query API returns aggregated metrics for integrations and scripts.

Ingest API

POST https://ingest.dumbledor.com/v1/collect accepts pageviews, custom events, and identify calls. Pass your website ID as websiteId in the JSON body. No API key is required.

bash

curl https://ingest.dumbledor.com/v1/collect \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pageview",
    "websiteId": "YOUR_PROJECT_ID",
    "url": "https://dumbledor.com/pricing"
  }'

bash

curl https://ingest.dumbledor.com/v1/collect \
  -H "Content-Type: application/json" \
  -d '{
    "type": "track",
    "websiteId": "YOUR_PROJECT_ID",
    "name": "signup",
    "properties": { "plan": "pro" }
  }'

Field	Type	Description
type	pageview \| track \| identify	Event kind. Pageviews need url. Track needs name. Identify needs userId.
websiteId	uuid	Your website ID from project settings under Tracking.
url	string	Required for pageviews. Optional for track events.
name	string	Custom event name when type is track.
properties	object	Optional metadata for track events.
userId	string	Stable user identifier when type is identify.
referrer	string	Optional referrer URL for pageviews.
title	string	Optional page title for pageviews.

Successful requests return { "ok": true }. Events may be skipped when the plan limit is reached (skipped: "limit").

Query API

GET https://api.dumbledor.com/v1/metrics returns visitors, sessions, traffic series, and breakdowns. Authenticate with a secret key in the Authorization header.

Create keys in dashboard settings. Project secret keys start with sk_live_. Workspace keys also use the sk_live_ prefix and support scoped project access with permissions such as read and export.

bash

curl https://api.dumbledor.com/v1/metrics?range=7d \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY"

Field	Type	Description
range	query	60m, 24h, 7d, 30d, or 90d. Defaults to 7d.
projectId	query	Optional. Required when a workspace key covers multiple projects.

json

{
  "projectId": "YOUR_PROJECT_ID",
  "range": "7d",
  "metrics": [
    { "label": "Visitors", "value": "1,234", "change": "+12.3%", "positive": true }
  ],
  "traffic": [
    { "label": "Mon", "visitors": 120, "pageviews": 340 }
  ],
  "topPages": [
    { "path": "/", "visitors": 420, "share": 34 }
  ],
  "countries": [{ "label": "US", "value": 120, "share": 42 }],
  "referrers": [{ "label": "google.com", "value": 80, "share": 28 }],
  "browsers": [{ "label": "Chrome", "value": 210, "share": 61 }]
}

Key types

Secret keys (sk_live_) authenticate query API requests. Public keys (pk_live_) are reserved for the upcoming @dumbledor/sdk npm package and cannot access the query API today.