Skip to content

PopSQL: limited support.

Migrate now →

API, keys and outbound webhooks

The browsable reference, how to authenticate with a key, and the events the product pushes to your endpoint.

Reference

Every route is documented at `https://api.datarunner.app/docs` (OpenAPI at `/openapi/v1.json`). It is the same API the console uses — there is no separate "public" API with less in it.

API keys

A key (`dr_…`) belongs to a workspace and carries scopes: `queries:read`, `monitors:read`, and so on. The scope narrows on top of the role of whoever created the key, and a key never grants platform power. Available on Team (25) and Business (100).

Both accepted forms
curl -H "X-Api-Key: dr_…" https://api.datarunner.app/api/v1/queries
curl -H "Authorization: Bearer dr_…" https://api.datarunner.app/api/v1/queries

Outbound webhooks

Under Settings → Webhooks you register a URL and pick events. Every delivery is a POST with JSON `{ event, timestamp, data }` and, when a secret is set, the header `X-DataRunner-Signature: sha256=<HMAC of the body>`. The delivery log keeps 30 days of attempts with status, error and duration.

EventWhen
run.succeededa query run finished successfully
run.faileda query run failed
usage.threshold_crossedmonthly usage crossed 50%, 80% or 100% of the plan
data_quality.test_faileda quality test failed with warning or critical severity
Verifying the signature (Node)
const expected = 'sha256=' + crypto
  .createHmac('sha256', SECRET)
  .update(rawBody)
  .digest('hex');
if (expected !== req.headers['x-datarunner-signature']) return res.status(401).end();