DB-Master5 API

A heavy master-data distribution API: multi-gigabyte snapshot exports, continuous replication and a live change stream across a fleet of distribution nodes. Reference datasets (timezones, countries, currencies, calendars) sit behind a small, stable set of GET endpoints that return versioned JSON.

Every response is plain JSON over HTTPS. No SDK is required. Public endpoints (health, status, regions) need no authentication; dataset endpoints require an API key passed as a Bearer token.

Quickstart

1. Get an API key. Pick a plan on the pricing page and we will provision a key. Keys must be at least 8 characters long.

2. Check that the node is up — no key needed:

# Liveness check against the nearest distribution node
curl -s https://main.db-master5.info/v1/health

3. Make an authenticated request with your key as a Bearer token:

# Look up a country by ISO code
curl -s https://main.db-master5.info/v1/countries?code=NL \
  -H "Authorization: Bearer $DBM5_KEY"

That is it. The same calls work against any distribution node in the fleet.

Base URL & nodes

All requests go to a node base URL:

https://{node}.db-master5.info/v1

{node} is a distribution-node label, for example main (primary, core), a2 (edge) or b3 (replica). Fetch the full list any time from GET /v1/regions. Pin a node with its subdomain, or let anycast routing pick the nearest one. Your current node is main.db-master5.info.

Response headers

Every response includes:

X-Request-Id — a unique ID for the request, useful for support.
X-DbMaster5-Region — the node code that served the response.

Authenticated (protected) endpoints additionally return rate-limit headers:

X-RateLimit-Limit — requests allowed in the window (1000).
X-RateLimit-Remaining — requests remaining in the current window.
X-RateLimit-Reset — Unix timestamp when the window resets.

Authentication

Dataset endpoints require an API key. Pass it as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Alternatively, send it in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Keys must be at least 8 characters. Requests to protected endpoints without a valid key return 401 unauthorized. Public endpoints ignore the header.

Examples in three languages:

# curl
curl -s https://main.db-master5.info/v1/timezones \
  -H "Authorization: Bearer $DBM5_KEY"

// JavaScript (fetch)
const res = await fetch("https://main.db-master5.info/v1/countries?code=NL", {
  headers: { Authorization: `Bearer ${process.env.DBM5_KEY}` }
});
const data = await res.json();

# Python (requests)
import os, requests

res = requests.get(
    "https://main.db-master5.info/v1/time",
    params={"tz": "Europe/Moscow"},
    headers={"Authorization": f"Bearer {os.environ['DBM5_KEY']}"},
)
data = res.json()

API reference

All endpoints are GET only. Any other method returns 405 method_not_allowed. Paths below are relative to https://{node}.db-master5.info/v1.

Method	Path	Auth	Description
GET	`/health`	None	Liveness probe.
GET	`/status`	None	Distribution node status.
GET	`/regions`	None	List distribution nodes.
GET	`/timezones`	Bearer	Timezones with current offsets.
GET	`/countries`	Bearer	Country reference data.
GET	`/time`	Bearer	Current time for a timezone.

GET /health

Liveness probe. No authentication. Returns the serving node and a timestamp.

curl -s https://main.db-master5.info/v1/health

{
  "status": "ok",
  "region": "main",
  "timestamp": "2026-05-28T12:00:00+00:00"
}

GET /status

Distribution node status. No authentication. Reports the build, node role/tier, number of nodes online and latency.

curl -s https://main.db-master5.info/v1/status

{
  "status": "operational",
  "build": "2026.5.3",
  "region": {
    "code": "main",
    "role": "primary",
    "tier": "core"
  },
  "nodes_online": 14,
  "latency_ms": 12,
  "timestamp": "2026-05-28T12:00:00+00:00"
}

GET /regions

Lists all distribution nodes. No authentication. Each entry has a code, role, tier, the datasets it serves and an endpoint base URL.

curl -s https://main.db-master5.info/v1/regions

{
  "object": "list",
  "count": 14,
  "data": [
    {
      "code": "main",
      "role": "primary",
      "tier": "core",
      "datasets": ["timezones", "countries", "currencies", "calendars"],
      "endpoint": "https://main.db-master5.info/v1"
    }
  ]
}

GET /timezones

Lists timezones with their current UTC offset. Requires authentication.

curl -s https://main.db-master5.info/v1/timezones \
  -H "Authorization: Bearer $DBM5_KEY"

{
  "object": "list",
  "count": 12,
  "data": [
    {
      "timezone": "Europe/Moscow",
      "abbreviation": "MSK",
      "utc_offset": "+03:00"
    }
  ]
}

GET /countries

Country reference data. Requires authentication.

Query parameters

Parameter	Type	Description
`code`	string	Filter by ISO 3166-1 alpha-2 or alpha-3 code (e.g. `NL` or `NLD`).
`currency`	string	Filter by ISO 4217 currency code (e.g. `EUR`).

curl -s "https://main.db-master5.info/v1/countries?code=NL" \
  -H "Authorization: Bearer $DBM5_KEY"

{
  "object": "list",
  "count": 1,
  "data": [
    {
      "iso2": "NL",
      "iso3": "NLD",
      "name": "Netherlands",
      "capital": "Amsterdam",
      "region": "Europe",
      "currency": "EUR",
      "calling_code": "+31"
    }
  ]
}

Omitting both parameters returns the full dataset. Filters can be combined.

GET /time

Current time for a timezone. Requires authentication.

Query parameters

Parameter	Type	Description
`tz`	string	IANA timezone name (e.g. `Europe/Moscow`). Defaults to the serving node’s timezone. An unknown value returns `422 invalid_argument`.

curl -s "https://main.db-master5.info/v1/time?tz=Europe/Moscow" \
  -H "Authorization: Bearer $DBM5_KEY"

{
  "timezone": "Europe/Moscow",
  "datetime": "2026-05-28T15:00:00+03:00",
  "unixtime": 1779019200,
  "utc_offset": "+03:00",
  "abbreviation": "MSK",
  "day_of_week": 4,
  "week_number": 22
}

day_of_week follows ISO-8601 (1 = Monday … 7 = Sunday); week_number is the ISO week.

Errors

Errors use a consistent envelope and standard HTTP status codes:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key. Pass it via the Authorization: Bearer header.",
    "status": 401
  }
}

HTTP	Code	When it happens
401	`unauthorized`	Missing or invalid API key on a protected endpoint.
404	`not_found`	Unknown endpoint path.
405	`method_not_allowed`	A method other than `GET` was used.
422	`invalid_argument`	An invalid parameter, such as an unknown `tz`.

The complete machine-readable contract is published as an OpenAPI 3 spec.

Real-time & bulk (v3)

High-volume integrations don’t poll. The /v3/api surface adds a live change stream, bulk snapshot exports and the distribution-node inventory, served from the same nodes. Base URL: https://{node}.db-master5.info/v3/api.

GET /v3/api/stream

A Server-Sent Events feed of dataset changes. Open one persistent connection per integration and receive every update the moment it lands — no polling, no rate-limit churn. Connections are long-lived; the stream sends a heartbeat comment between events.

curl -N https://main.db-master5.info/v3/api/stream \
  -H "Authorization: Bearer $DBM5_KEY"

event: change
data: {"seq":1402553,"dataset":"timezones","op":"update","rev":"r1a2b3c4","region":"main","ts":"2026-05-28T12:00:00+00:00"}

event: change
data: {"seq":1402554,"dataset":"countries","op":"update","rev":"r5d6e7f8","region":"main","ts":"2026-05-28T12:00:03+00:00"}

Resume after a disconnect by sending the last seen sequence in the Last-Event-ID header.

GET /v3/api/snapshots

Lists point-in-time dataset snapshots — nightly full dumps (tens of GB) plus hourly incremental diffs, compressed as jsonl.zst and continuously replicated to every distribution node.

curl -s https://main.db-master5.info/v3/api/snapshots

{
  "object": "list",
  "count": 14,
  "dataset_bytes": 41372138496,
  "retention_days": 30,
  "replication": "continuous",
  "data": [
    {
      "id": "snap_20260528a1b2",
      "kind": "full",
      "format": "jsonl.zst",
      "size_bytes": 41372138496,
      "download_url": "https://main.db-master5.info/v3/api/exports/snap_20260528a1b2.jsonl.zst",
      "status": "available"
    }
  ]
}

Fetch a snapshot’s download_url to stream the export as newline-delimited JSON (application/x-ndjson, chunked transfer). Full datasets run to tens of gigabytes — stream them, don’t buffer.

GET /v3/api/hosts

Lists the distribution nodes backing the fleet. No authentication. Each entry has an id, the node region code, its role, tier and health status.

curl -s https://main.db-master5.info/v3/api/hosts

{
  "object": "list",
  "count": 13,
  "data": [
    {
      "id": "node-main",
      "region": "main",
      "role": "primary",
      "tier": "core",
      "status": "healthy"
    }
  ]
}