The API v1 foundation

API versioning

The current, and so far only, version is v1, under the base path /api/v1. Every response carries its own apiVersion: "v1" field. A future breaking change would ship as a new version rather than silently altering what v1 already returns.

Standard response envelope

Every endpoint returns the same shape:

{
  "apiVersion": "v1",
  "status": "live" | "delayed" | "reference" | "historical" | "stale" | "unavailable" | "invalid_request" | "error",
  "data": { /* the requested figure, or null */ } | null,
  "error": { "code": "...", "message": "..." } | null,
  "meta": { "requestedAt": "2026-01-01T00:00:00.000Z" }
}

Whether data is fresh, aging, a reference figure, historical, or simply not available yet is reported inside the body via status — it is a data-availability fact, not treated as an HTTP-level error. Only a malformed request (invalid_request, HTTP 400) or a genuine internal failure (error, HTTP 500) breaks from HTTP 200.

Timestamps, freshness, and unavailable/error behavior

Timestamps are ISO 8601 strings throughout — an observation's observedAt and receivedAt, and the request's own meta.requestedAt. When no verified observation exists, the API returns status: "unavailable" with data: null — never an estimated, rounded, or previously-cached figure presented as current. An internal failure returns a generic error status with a fixed { code, message }, never internal exception detail.

Numeric representation

Live/reference metal and FX figures are plain JSON numbers. Historical monthly prices are returned as exact decimal strings (e.g. "4073.000000") rather than a JSON number, since the underlying value is stored to a fixed decimal precision a binary floating-point number cannot always represent exactly — parse it as a decimal, not a float, if precision matters to your use case.

Data provenance policy

Every price/rate object carries its own provider, source, and (for historical records) license field. This platform's public-facing surfaces — this API included — use the same generic "Platform Reference" label the rest of the site already uses for its live commercial data provider, rather than naming that provider directly here; see Sources & Data Methodology for the full, voluntary provider-by-provider disclosure this platform maintains.