Developers · contract metrics-exchange/1

Metrics Exchange API

Pull the VibeBack numbers a workspace owner chose to share — conversations, tickets, satisfaction, website traffic, payments and more — for any date range, as JSON, XML or CSV. Pull only: you ask whenever you like; VibeBack never calls you.

The doors

Every response carries X-Request-Id; every data document carries a query_id. Every timestamp is ISO 8601 with an offset. Dates you send are read in the client’s timezone. Weeks start on Monday.

Authentication

Exchange the client id and secret you received from the workspace owner for an opaque token (OAuth 2 client credentials, RFC 6749 §4.4). Send it as Authorization: Bearer …. Renew before expires_in; do not parse the token. A revoked or deleted client’s tokens stop working on the next request.

# 1. Get a token
curl -X POST 'https://api.vibeback.io/metrics-exchange/v1/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=<id>&client_secret=<secret>'

# 2. Check the time windows
curl 'https://api.vibeback.io/metrics-exchange/v1/time' -H 'Authorization: Bearer <token>'

# 3. See every metric you may ask for
curl 'https://api.vibeback.io/metrics-exchange/v1/catalogue' -H 'Authorization: Bearer <token>'

# 4. Dry run: the exact shape, zero values
curl 'https://api.vibeback.io/metrics-exchange/v1/data?metrics=*&range=last_7_days&group=day&dry_run=true' -H 'Authorization: Bearer <token>'

# 5. Real numbers, yesterday, as CSV
curl 'https://api.vibeback.io/metrics-exchange/v1/data?metrics=*&range=yesterday&format=csv' -H 'Authorization: Bearer <token>'

Time

GET /time returns the provider clock, your client’s timezone, data_as_of and the exact window of every shortcut (to is exclusive; last_7_days excludes today; this_week and this_month include it)./data echoes the same window in period, so both sides always mean the same “today”. Bucket boundaries are exact instants: a daylight-saving night never merges or loses an hour.

Catalogue

GET /catalogue lists only the metrics your client may ask for, each with its id, version, label, description, unit, kind, allowed breakdowns, available_from and a sample_point — so you can build your mapping before any real data flows. Only count and sum may be added across periods; never add distinct, ratio orgauge. A ratio always carries its numerator and denominator.

Data

GET /data takes these parameters (or POST /data with the same names as a JSON body). Give exactly one of from + to, range or date.

Upsert on (metric id, start, breakdown) — never append. final: false marks an open period; a closed period can still change when a record is restored from Trash or permanently deleted, or a payment is refunded. Breakdown groups smaller than 5 are merged into Other. A dry run (dry_run=true) returns the full document with zeros and costs a tenth of a request.

Daily pull

Most receivers pull once a day. A day runs from midnight to midnight in your client’s timezone, which /time and every answer state. Every VibeBack number is stamped with the server’s clock when it happens, so yesterday is complete and final: true as soon as your midnight has passed. Pull the last 7 days rather than only yesterday: one request still carries every metric, and upserting it picks up the corrections described above. For history, ask one calendar month at a time, starting each metric at its own available_from. A whole year in one request is over the 10,000-point cap and is refused with TOO_MANY_POINTS. A window that starts before any requested metric’s available_from is refused with RANGE_BEFORE_AVAILABLE; ask for a metric that started recently in its own request.

# Every day, after midnight in your client's timezone: the last 7 full days,
# one point per metric per day. Upsert on (metric, start, breakdown) so later corrections replace earlier values.
curl 'https://api.vibeback.io/metrics-exchange/v1/data?metrics=*&range=last_7_days&group=day&format=csv' -H 'Authorization: Bearer <token>'

# One chosen day
curl 'https://api.vibeback.io/metrics-exchange/v1/data?metrics=*&date=2026-10-25&format=csv' -H 'Authorization: Bearer <token>'

# First run: fetch history one calendar month per request (at most 31 points per metric).
# Start each metric at its own available_from (see /catalogue); an earlier month is refused with RANGE_BEFORE_AVAILABLE.
curl 'https://api.vibeback.io/metrics-exchange/v1/data?metrics=*&from=2026-09-01&to=2026-10-01&group=day&format=csv' -H 'Authorization: Bearer <token>'

Formats and paging

JSON is the master shape. XML is the same tree with fixed element names, validated by /schema.xsd. CSV is long format, one row per point, with these 18 columns: query_id, dry_run, metric_id, metric_version, label, unit, kind, start, end, value, currency, numerator, denominator, final, breakdown_name, breakdown_value, timezone, data_as_of. An answer is at most 10,000 points; a longer one is paged from a frozen snapshot — follow next_page, the X-Next-Page header or the Link: rel="next"header until it is empty. A cursor that expired or belongs to another query answers INVALID_RANGE: start again from page one.

The spec files https://api.vibeback.io/metrics-exchange/v1/openapi.json (OpenAPI 3.1) and https://api.vibeback.io/metrics-exchange/v1/schema.xsd need a token, like every door except /token.

Errors

Every error is Problem Details JSON (RFC 9457), whatever format you asked for, with a stable code.

Limits

Free, with fair-use limits shown to the owner on their screen: by default 1,000 data requests per client per day (a dry run counts 0.1), 20 token calls a minute per address and client, 60 a minute per address, 60 calls a minute per client to /health, /time, /catalogue and the spec files together, and 10,000 points per answer. Over a limit you get RATE_LIMITED with Retry-After — never partial data.

Receiver checklist

1. Store the id and secret; get a token; renew before it expires.
2. Call /time once a day and after any clock or daylight-saving doubt.
3. Call /catalogue once a day, on METRIC_NOT_ALLOWED, and when /health’s metrics_enabled changes.
4. Test your pipeline with dry_run=true before go-live.
5. Pull /data no faster than the client’s freshness interval. Upsert. Show provisional points as such.
6. Follow paging until it is empty; on INVALID_RANGE for a cursor, restart from page one.
7. Watch notices for metric withdrawals (30 days’ notice).

Conformance

Check any provider — VibeBack or your own — with the conformance script (Python 3.11+, standard library only):metrics-exchange-conformance.py.

python3 metrics-exchange-conformance.py --base https://api.vibeback.io/metrics-exchange/v1 \
  --client-id <id> --client-secret <secret> --formats

Metrics VibeBack offers

A workspace owner ticks which of these a client may pull, per level. Platform totals exclude internal workspaces; workspace and website figures count everything.