Documentation

API Reference

Complete reference for the MetricRegistry REST API. Base URL: https://api.metricregistry.co.uk

Authentication

All requests require a Bearer token in the Authorization header. Get your API key from the Getting Started guide.

request header

Authorization: Bearer mr_live_abc123...

Rate Limits

Rate limits are applied per API key. The response includes X-RateLimit-Remaining and X-RateLimit-Reset headers.

Tier	Rate Limit	Burst	Cost
Open	100 / min	10 / sec	Free
Pro	10,000 / min	200 / sec	$99/mo
Enterprise	Unlimited	Custom	Custom

Endpoints

Method	Path	Description
GET	/v1/metrics	List all metrics with optional filters
GET	/v1/metrics/:id	Get a single metric by fully qualified ID
GET	/v1/metrics/search	Full-text search across metric definitions
POST	/v1/validate	Validate SQL against a metric definition
POST	/v1/keys	Create a new API key
GET	/v1/industries	List available industries and metric counts
GET	/v1/metrics/:id/history	Get version history for a metric
POST	/v1/export/dbt	Export metrics as dbt YAML

GET/v1/metrics

List metrics with optional query parameters for filtering.

Parameter	Type	Description
industry	string	Filter by industry (banking, healthcare, esg)
certification	string	Filter by certification status (draft, certified)
limit	integer	Max results (default 50, max 200)
offset	integer	Pagination offset (default 0)

example response

{
  "total": 150,
  "limit": 50,
  "offset": 0,
  "metrics": [
    {
      "id": "uk.banking.capital.cet1_ratio",
      "title": "CET1 Ratio",
      "version": "0.1.0",
      "certification": "draft",
      "industry": "banking"
    }
  ]
}

GET/v1/metrics/:id

Get a single metric with full detail including formula, inputs, regulatory source, provenance, thresholds, and related metrics.

example response

{
  "id": "uk.banking.capital.cet1_ratio",
  "title": "CET1 Ratio",
  "version": "0.1.0",
  "certification": "draft",
  "description": "Common Equity Tier 1 capital expressed as a percentage of risk-weighted assets.",
  "formula": {
    "dialect": "ansi",
    "sql": "SELECT ${cet1_capital} / nullif(${rwa}, 0) AS cet1_ratio FROM ${capital}"
  },
  "output": {
    "column": "cet1_ratio",
    "type": "numeric",
    "unit": "ratio"
  },
  "frequency": "quarterly",
  "inputs": [
    {
      "dataset": "capital",
      "dataset_description": "Regulatory capital figures at the reporting date",
      "columns": [
        { "name": "cet1_capital", "type": "numeric" },
        { "name": "rwa", "type": "numeric" }
      ]
    }
  ],
  "regulatory_source": {
    "framework": "Basel 3.1 PS1/26",
    "paragraph": "Article 92(2)(a)",
    "url": "https://www.bankofengland.co.uk/prudential-regulation/publication/2024/ps1-26"
  },
  "thresholds": [
    { "type": "regulatory_minimum", "value": 0.045, "source": "CRR Article 92(1)(a)" }
  ],
  "related_metrics": [
    "uk.banking.capital.tier1_capital_ratio"
  ]
}

POST/v1/validate

Validate a SQL implementation against a canonical metric definition. Requires Pro or Enterprise tier.

request body

{
  "metric_id": "uk.banking.capital.cet1_ratio",
  "sql": "SELECT cet1_capital / nullif(rwa, 0) AS cet1_ratio FROM capital"
}

response

{
  "valid": true,
  "metric_id": "uk.banking.capital.cet1_ratio",
  "checks": {
    "output_column": "pass",
    "input_datasets": "pass",
    "null_safety": "pass",
    "column_references": "pass"
  },
  "warnings": []
}

POST/v1/export/dbt

Export metric definitions as dbt-compatible YAML. Requires Enterprise tier.

request body

{
  "metric_ids": [
    "uk.banking.capital.cet1_ratio",
    "uk.banking.capital.tier1_capital_ratio"
  ],
  "format": "dbt_yaml"
}

response

{
  "format": "dbt_yaml",
  "content": "version: 2\nmetrics:\n  - name: cet1_ratio\n    label: CET1 Ratio\n    ..."
}

Error Codes

Code	Meaning
401	Missing or invalid API key
403	Endpoint requires a higher tier
404	Metric not found
429	Rate limit exceeded
500	Internal server error