REST API in development

Metrical Digital API — Developer Documentation

Programmatic access to everything Metrical offers. Run performance audits, retrieve results, and monitor Core Web Vitals directly from your code.

Machine-readable resources

Available now at stable URLs, for agents, integrations, and tooling.

API index /api
JSON entry point: versions, endpoints, the deprecation policy, and the error format.
OpenAPI 3.1 specification /openapi.json
Machine-readable description of the live Metrical Digital API endpoints.
API catalog /.well-known/api-catalog
RFC 9727 linkset pointing at the OpenAPI description and this documentation.
llms.txt /llms.txt
Curated index of every page on metrical.digital, for language models.
llms-full.txt /llms-full.txt
The whole site as Markdown in a single response.
Sitemap /sitemap.xml
Every indexable URL with last-modified dates.
Crawler policy /robots.txt
Robots Exclusion Protocol rules. All major AI agents are explicitly allowed.

Every page on this site also has a Markdown representation. Send Accept: text/markdown, or append .md to the path — for example /developers.md.

Metrical Digital API endpoints

Live on https://metrical.digital and described in the OpenAPI specification. They authenticate with the browser session — a signed-in customer session, or the metrical_guest_session_id cookie issued on first visit.

GET /api/v1/scan/{scanId}/report

Export a completed scan report as CSV, JSON, or Markdown.

Unversioned alias: /api/scan/{scanId}/report

POST /api/v1/scans/{scanId}/feedback

Submit feedback on a scan result.

Unversioned alias: /api/scans/{scanId}/feedback

/api returns the same list as JSON, along with every version and its lifecycle state.

Versioning and deprecation

Every endpoint is available under a version prefix, currently /api/v1. Breaking changes ship as a new prefix; the existing one keeps working.

The current version is v1, served from https://metrical.digital/api/v1.
Additive changes — new endpoints, new optional parameters, new response fields — ship within the current version. Treat unknown response fields as forwards-compatible and ignore them.
A change that would break an existing client ships as a new version prefix. The previous version keeps responding until its sunset date.
A version is never sunset with less than 180 days of notice.
Once deprecated, every response from that version carries a `Deprecation` header (RFC 9745), a `Sunset` header (RFC 8594), and a `Link` header with `rel="successor-version"`.
The unversioned paths under https://metrical.digital/api are permanent aliases of the current version and move with it. Pin to a version prefix if that matters to you.
Every response names the version that produced it in the `API-Version` header.

The current version is v1. The policy is also published as JSON at /api and as the x-api-versioning extension in /openapi.json.

Error responses

Every failure returns JSON, including unknown paths and unsupported methods. error.code is stable and safe to branch on; error.hint describes how to recover.

{
  "error": {
    "code": "not_found",
    "message": "No API endpoint exists at GET /api/nope.",
    "hint": "Check the path and method against the OpenAPI description at https://metrical.digital/openapi.json.",
    "status": 404,
    "documentation_url": "https://metrical.digital/developers",
    "specification_url": "https://metrical.digital/openapi.json"
  },
  "message": "No API endpoint exists at GET /api/nope."
}

Codes: not_found, method_not_allowed, unauthorized, invalid_request, quota_exceeded, upstream_error.

What you'll be able to do

Run scans programmatically

Trigger performance audits from your CI/CD pipeline, scripts, or applications. Get the same thorough analysis you see in the dashboard, via a simple REST API.

Retrieve structured results

Access scan results as structured JSON. Core Web Vitals, performance scores, prioritised recommendations, and plain English explanations. All machine-readable.

Monitor over time

Track performance trends across deploys. Set up scheduled scans and get notified when metrics regress beyond thresholds you define.

Integrate with your tools

Build custom dashboards, feed data into Slack or PagerDuty, or block deploys that fail performance budgets. The API gives you the data and you decide what to do with it.

Designed for developer experience

Simple REST endpoints

No complex SDKs or heavy dependencies. Standard HTTP requests with JSON responses. If you can use fetch, you can use the Metrical API.

API key authentication

Straightforward API key auth. Generate keys from your dashboard, scope them to specific permissions, and rotate them when needed.

Webhooks for async results

Scans take time to run properly. Register a webhook URL and get notified when results are ready. No polling required.

Get notified when it launches

The API is currently in development. If you're interested in early access or have specific use cases you'd like supported, we'd love to hear from you.