{
  "name": "Metrical Digital API",
  "description": "HTTP endpoints for Metrical, a web performance auditing tool that runs real-browser Core Web Vitals scans on any public URL.",
  "documentation_url": "https://metrical.digital/developers",
  "specification_url": "https://metrical.digital/openapi.json",
  "current_version": "v1",
  "versions": [
    {
      "version": "v1",
      "status": "current",
      "base_url": "https://metrical.digital/api/v1",
      "released": "2026-08-25",
      "deprecated": null,
      "sunset": null,
      "successor": null
    }
  ],
  "versioning": {
    "strategy": "url-path",
    "summary": "Every endpoint is available under a version prefix, currently /api/v1. Breaking changes ship as a new prefix; the existing one keeps working.",
    "current_version": "v1",
    "current_base_url": "https://metrical.digital/api/v1",
    "unversioned_alias_url": "https://metrical.digital/api",
    "rules": [
      "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."
    ],
    "deprecation": {
      "notice_days": 180,
      "headers": [
        "Deprecation",
        "Sunset",
        "Link; rel=\"successor-version\""
      ],
      "specifications": [
        "RFC 9745 (Deprecation)",
        "RFC 8594 (Sunset)"
      ]
    },
    "policy_url": "https://metrical.digital/developers#versioning"
  },
  "endpoints": [
    {
      "method": "GET",
      "path": "/api/v1/scan/{scanId}/report",
      "url": "https://metrical.digital/api/v1/scan/{scanId}/report",
      "summary": "Export a completed scan report as CSV, JSON, or Markdown.",
      "authentication": "session"
    },
    {
      "method": "POST",
      "path": "/api/v1/scans/{scanId}/feedback",
      "url": "https://metrical.digital/api/v1/scans/{scanId}/feedback",
      "summary": "Submit feedback on a scan result.",
      "authentication": "session"
    }
  ],
  "authentication": {
    "type": "session cookie",
    "description": "These endpoints authenticate with the browser session: a signed-in customer session, or the metrical_guest_session_id cookie issued on first visit.",
    "api_keys": "Not yet available. API-key authentication ships with the standalone REST API — see the developer documentation for status."
  },
  "errors": {
    "description": "Every failure returns JSON, including unknown paths and wrong methods. `error.code` is stable and safe to branch on.",
    "schema_url": "https://metrical.digital/openapi.json#/components/schemas/Error",
    "codes": [
      "not_found",
      "method_not_allowed",
      "unauthorized",
      "invalid_request",
      "quota_exceeded",
      "upstream_error"
    ]
  }
}