# Metrical Digital API — Developer Documentation

> Developer resources for Metrical Digital: OpenAPI specification, HTTP endpoints, authentication, report export formats, and API early access.

_Source: https://metrical.digital/developers — Markdown: https://metrical.digital/developers.md — Part of Metrical (https://metrical.digital)._

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

## Machine-readable resources

| Resource | URL | Media type |
| --- | --- | --- |
| API index | <https://metrical.digital/api> | `application/json` |
| OpenAPI 3.1 specification | <https://metrical.digital/openapi.json> | `application/openapi+json` |
| API catalog (RFC 9727) | <https://metrical.digital/.well-known/api-catalog> | `application/linkset+json` |
| llms.txt index | <https://metrical.digital/llms.txt> | `text/plain` |
| llms-full.txt (full corpus) | <https://metrical.digital/llms-full.txt> | `text/plain` |
| Sitemap | <https://metrical.digital/sitemap.xml> | `application/xml` |
| Crawler policy | <https://metrical.digital/robots.txt> | `text/plain` |

Every prose page on metrical.digital also has a Markdown representation. Request it with
`Accept: text/markdown`, or append `.md` to the path:

```sh
curl -H 'Accept: text/markdown' https://metrical.digital/developers
curl https://metrical.digital/developers.md
```

## Available today

The endpoints below are 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 — and are intended for use from the
Metrical web app.

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

Export a completed scan report. The `format` query parameter accepts `csv` (default),
`json`, or `markdown`. Returns `401` without a session, and the upstream status when the
report cannot be generated.

Unversioned alias: `GET /api/scan/{scanId}/report`.

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

Submit feedback on a scan result. Accepts a JSON body and returns the upstream response.

Unversioned alias: `POST /api/scans/{scanId}/feedback`.

## 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 policy is published as JSON at <https://metrical.digital/api> and as the
`x-api-versioning` extension in <https://metrical.digital/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.

```json
{
  "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`.

## Planned

A standalone REST API with API-key authentication is in development and not yet released. When
it ships it will cover:

- **Run scans programmatically** from CI/CD pipelines, scripts, and applications.
- **Retrieve structured results** as JSON: Core Web Vitals, performance scores, prioritised
  recommendations, and plain-English explanations.
- **Monitor over time** with scheduled scans and threshold-based alerts.
- **Webhooks for async results** so you do not have to poll while a scan runs.

API access is included in the Pro plan. To register interest or describe a use case you need
supported, get in touch at <https://metrical.digital/contact>.