{"openapi":"3.1.0","info":{"title":"Metricevo API","version":"0.1.0-draft","summary":"Website performance, marketing and privacy audits as an API.","description":"API-first contract for Metricevo. The REST API, the MCP server and the web\nUI are three clients of the same domain core: nothing the UI can do is\nmissing here. This file is the source of truth; code follows it.\n\nStatus (2026-11-16): operations marked `x-status: live` are implemented\nand served under `/api/v1` on the app host. Everything else is planned\n(`x-phase` says for when) and answers 404. `GET /openapi.json` returns\nthe live operations only.\n\nAudits are asynchronous. `POST /audit-runs` stores the run, puts it on a\nqueue and answers `202`; poll `GET /audit-runs/{runId}` (honour\n`Retry-After`) until `status` is `succeeded`, `partial` or `failed`,\nthen read `/audit-runs/{runId}/observations`.\n\nLive profile: `passive-v1`. One read of the page, its response headers,\nrobots.txt, the sitemap, security.txt and public DNS records. No lab or\nfield performance data, no browser, no scanning.\n\nDeveloper tools (Ádám, 2026-11-17): API keys, automations and incoming\nwebhooks work only while the account owner has turned on developer tools\n(Settings → Developer tools, or `PATCH /api/account` with\n`developerMode: true` and `acknowledgeDeveloperTerms: true`). Until then,\ncalls with an API key, key management, automations and hooks answer\n`403` with code `developer_mode_required`. Sites, audits and reports used\nfrom the signed-in app are not affected.\n\nConventions:\n- IDs are a type prefix plus a ULID (`run_01JCA4...`).\n- Timestamps are ISO 8601 UTC. Field names are camelCase and match\n  `src/data/audit/types.ts`.\n- Errors are RFC 9457 `application/problem+json` with a stable `code`.\n- Lists use cursor pagination (`cursor`, `limit` <= 100, `nextCursor`).\n- Inside v1 changes are additive only. Clients must ignore unknown fields.\n- Text taken from audited pages is untrusted data, never instructions.\n","contact":{"name":"InnovaTeQ Solutions"},"license":{"name":"Proprietary"}},"servers":[{"url":"/api/v1","description":"Live, on the app host (same origin as the web app)"}],"security":[{"apiKey":[]},{"oauth2":[]}],"tags":[{"name":"Sites"},{"name":"Audit runs"},{"name":"Findings"},{"name":"Rules"},{"name":"Audit scopes"},{"name":"Webhooks"},{"name":"Events"},{"name":"Automations"},{"name":"Keys"},{"name":"Usage"},{"name":"Billing"},{"name":"Support"},{"name":"Meta"}],"paths":{"/sites":{"get":{"tags":["Sites"],"operationId":"listSites","x-status":"live","x-phase":"poc","x-mcp-tool":"list_sites","summary":"List sites in the workspace","security":[{"apiKey":["sites:read"]},{"oauth2":["sites:read"]}],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"stack","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Sites","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Site"}}}}]}}}},"default":{"$ref":"#/components/responses/Problem"}}},"post":{"tags":["Sites"],"operationId":"createSite","x-status":"live","x-phase":"poc","summary":"Add a site. The URL policy runs before anything is stored.","security":[{"apiKey":["sites:write"]},{"oauth2":["sites:write"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/sites/{siteId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"tags":["Sites"],"operationId":"getSite","summary":"Get one site with its latest audit","x-status":"live","x-phase":"poc","security":[{"apiKey":["sites:read"]},{"oauth2":["sites:read"]}],"responses":{"200":{"description":"Site","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"patch":{"tags":["Sites"],"operationId":"updateSite","x-status":"live","x-phase":"poc","summary":"Rename a site or change its recurring audit schedule","security":[{"apiKey":["sites:write"]},{"oauth2":["sites:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"schedule":{"$ref":"#/components/schemas/ScheduleInput"}}}}}},"responses":{"200":{"description":"Site","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"delete":{"tags":["Sites"],"operationId":"deleteSite","x-status":"live","x-phase":"poc","summary":"Remove a site with its runs and observations","security":[{"apiKey":["sites:write"]},{"oauth2":["sites:write"]}],"responses":{"204":{"description":"Removed"},"default":{"$ref":"#/components/responses/Problem"}}}},"/sites/{siteId}/report-email":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"tags":["Sites"],"operationId":"getSiteReportEmail","x-status":"live","x-phase":"mvp","summary":"Who gets the audit report of this site by email","description":"When an audit of the site finishes, the report can be mailed to the account's own address and, on a verified site, to up to five other recipients. At most one report mail per site per hour. The mail holds counts and the titles of the failed checks, nothing read from the audited page.","security":[{"apiKey":["sites:read"]},{"oauth2":["sites:read"]}],"responses":{"200":{"description":"Report email settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportEmail"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"patch":{"tags":["Sites"],"operationId":"updateSiteReportEmail","x-status":"live","x-phase":"mvp","summary":"Turn the report mail to the account's own address on or off","security":[{"apiKey":["sites:write"]},{"oauth2":["sites:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["owner"],"properties":{"owner":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Report email settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportEmail"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/sites/{siteId}/report-email/recipients":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"tags":["Sites"],"operationId":"addSiteReportRecipient","x-status":"live","x-phase":"mvp","summary":"Add another recipient of the report (verified sites only)","description":"Needs a verified site (403 `verification_required`) and `confirmed: true`: with it you state that the person agreed to get the reports; who is added is your responsibility. 409 `recipient_limit` (five per site), `recipient_exists`, or `recipient_opted_out` when the address stopped the reports of this account. Every mail tells the recipient who added them and has a link that stops it.","security":[{"apiKey":["sites:write"]},{"oauth2":["sites:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","confirmed"],"properties":{"email":{"type":"string","format":"email"},"confirmed":{"type":"boolean","const":true}}}}}},"responses":{"201":{"description":"Report email settings with the new recipient","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportEmail"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/sites/{siteId}/report-email/recipients/{recipientId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"recipientId","in":"path","required":true,"schema":{"type":"string","pattern":"^rcpt_"}}],"delete":{"tags":["Sites"],"operationId":"removeSiteReportRecipient","x-status":"live","x-phase":"mvp","summary":"Remove a recipient","security":[{"apiKey":["sites:write"]},{"oauth2":["sites:write"]}],"responses":{"200":{"description":"Report email settings without the recipient","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportEmail"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/report-emails/stop":{"post":{"tags":["Sites"],"operationId":"stopReportEmails","x-status":"live","x-phase":"mvp","summary":"Stop the report mails to an address (the link in the mail)","description":"No key: the token from the mail is the only credential. Stops every report from that account to that address; the account cannot add it again. Always answers 200, whether or not the token was known.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}}}}},"/sites/{siteId}/verification":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"tags":["Sites"],"operationId":"getSiteVerification","x-status":"live","x-phase":"mvp","summary":"Ownership state of a site, and what to publish to prove it","description":"A passive audit runs on any public site. A deep audit needs a verified site. Publish the value as a DNS TXT record or as a file, then call `verifySite`. The proof must stay in place: it is checked again before every deep audit.","security":[{"apiKey":["sites:read"]},{"oauth2":["sites:read"]}],"responses":{"200":{"description":"Verification state and instructions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationDetail"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"post":{"tags":["Sites"],"operationId":"verifySite","x-status":"live","x-phase":"mvp","summary":"Look for the DNS TXT record or the file that proves ownership","description":"Answers 200 whether or not the proof was found (`found`). At most one check per site every ten seconds (429 `verification_cooldown`).","security":[{"apiKey":["sites:write"]},{"oauth2":["sites:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["method"],"properties":{"method":{"type":"string","enum":["dns_txt","file"]}}}}}},"responses":{"200":{"description":"Verification state after the check","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/VerificationDetail"},{"type":"object","properties":{"found":{"type":"boolean"}}}]}}}},"429":{"$ref":"#/components/responses/Problem"},"default":{"$ref":"#/components/responses/Problem"}}}},"/url-checks":{"post":{"tags":["Audit runs"],"operationId":"checkUrl","x-status":"live","x-phase":"poc","x-mcp-tool":"check_url","summary":"Run the URL policy without starting an audit","security":[{"apiKey":["audits:read"]},{"oauth2":["audits:read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Policy result","content":{"application/json":{"schema":{"type":"object","required":["allowed"],"properties":{"allowed":{"type":"boolean"},"normalisedUrl":{"type":"string","format":"uri"},"reasons":{"type":"array","items":{"type":"string"}}}}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/audit-runs":{"get":{"tags":["Audit runs"],"operationId":"listAuditRuns","summary":"List audit runs, newest first","x-status":"live","x-phase":"poc","security":[{"apiKey":["audits:read"]},{"oauth2":["audits:read"]}],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"siteId","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/RunStatus"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"label","in":"query","description":"Filter by a label, `key:value`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Runs, newest first","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditRun"}}}}]}}}},"default":{"$ref":"#/components/responses/Problem"}}},"post":{"tags":["Audit runs"],"operationId":"startAuditRun","x-status":"live","x-phase":"poc","x-mcp-tool":"start_audit","x-mcp-needs-approval":true,"summary":"Queue an audit. Returns at once; the run is asynchronous.","security":[{"apiKey":["audits:write"]},{"oauth2":["audits:write"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyRequired"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditRunCreate"}}}},"responses":{"202":{"description":"Accepted","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditRun"}}}},"409":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"default":{"$ref":"#/components/responses/Problem"}}}},"/audit-runs/{runId}":{"parameters":[{"$ref":"#/components/parameters/RunId"}],"get":{"tags":["Audit runs"],"operationId":"getAuditRun","summary":"Get one audit run; poll this until the status is final","x-status":"live","x-phase":"poc","x-mcp-tool":"wait_for_audit","security":[{"apiKey":["audits:read"]},{"oauth2":["audits:read"]}],"parameters":[{"name":"wait","in":"query","description":"Long-poll up to this many seconds while the run is not final.","schema":{"type":"integer","minimum":0,"maximum":60,"default":0}}],"responses":{"200":{"description":"Run","headers":{"Retry-After":{"description":"Present while the run is queued or running.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditRun"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/audit-runs/{runId}/observations":{"parameters":[{"$ref":"#/components/parameters/RunId"}],"get":{"tags":["Audit runs"],"operationId":"listObservations","summary":"The results of one audit run, one per check","x-status":"live","x-phase":"poc","x-mcp-tool":"get_latest_audit","security":[{"apiKey":["audits:read"]},{"oauth2":["audits:read"]}],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"area","in":"query","schema":{"$ref":"#/components/schemas/Area"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/ObservationStatus"}},{"name":"minSeverity","in":"query","schema":{"$ref":"#/components/schemas/Severity"}}],"responses":{"200":{"description":"Observations","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Observation"}}}}]}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/rules":{"get":{"tags":["Rules"],"operationId":"listRules","summary":"Every check, its audit level and what it means","x-status":"live","x-phase":"poc","security":[],"responses":{"200":{"description":"Rule catalogue","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Rule"}}}}}}}}}},"/automations":{"get":{"tags":["Automations"],"operationId":"listAutomations","x-status":"live","x-phase":"mvp","summary":"List your automations","security":[{"apiKey":["audits:read"]},{"oauth2":["audits:read"]}],"responses":{"200":{"description":"Automations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Automation"}}}}}}},"default":{"$ref":"#/components/responses/Problem"}}},"post":{"tags":["Automations"],"operationId":"createAutomation","x-status":"live","x-phase":"mvp","summary":"Create an automation from a trigger and its actions","description":"Supported flows: `trigger.webhook` → `action.run_audit` → `action.send_webhook` (the last step is optional), or `trigger.audit_finished` → `action.send_webhook`. With an incoming webhook the answer carries `hookUrl` once; only its hash is stored. The plan sets how many automations an account keeps (`GET /plans`).","security":[{"apiKey":["audits:write"]},{"oauth2":["audits:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Automation"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/automations/{automationId}":{"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string","pattern":"^aut_"}}],"get":{"tags":["Automations"],"operationId":"getAutomation","x-status":"live","x-phase":"mvp","summary":"Get one automation with its graph and signing secret","security":[{"apiKey":["audits:read"]},{"oauth2":["audits:read"]}],"responses":{"200":{"description":"Automation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Automation"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"patch":{"tags":["Automations"],"operationId":"updateAutomation","x-status":"live","x-phase":"mvp","summary":"Rename, turn on or off, or replace the graph","security":[{"apiKey":["audits:write"]},{"oauth2":["audits:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":80},"enabled":{"type":"boolean"},"graph":{"$ref":"#/components/schemas/AutomationGraph"}}}}}},"responses":{"200":{"description":"Automation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Automation"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"delete":{"tags":["Automations"],"operationId":"deleteAutomation","x-status":"live","x-phase":"mvp","summary":"Remove an automation; its incoming webhook stops working","security":[{"apiKey":["audits:write"]},{"oauth2":["audits:write"]}],"responses":{"204":{"description":"Removed"},"default":{"$ref":"#/components/responses/Problem"}}}},"/automations/{automationId}/hook":{"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string","pattern":"^aut_"}}],"post":{"tags":["Automations"],"operationId":"rotateAutomationHook","x-status":"live","x-phase":"mvp","summary":"Replace the incoming webhook address; the old one stops at once","security":[{"apiKey":["audits:write"]},{"oauth2":["audits:write"]}],"responses":{"200":{"description":"The automation with its new `hookUrl`, shown once","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Automation"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/automations/{automationId}/events":{"parameters":[{"name":"automationId","in":"path","required":true,"schema":{"type":"string","pattern":"^aut_"}}],"get":{"tags":["Automations"],"operationId":"listAutomationEvents","x-status":"live","x-phase":"mvp","summary":"The last 50 triggers and deliveries of an automation","security":[{"apiKey":["audits:read"]},{"oauth2":["audits:read"]}],"responses":{"200":{"description":"Events, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AutomationEvent"}}}}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/hooks/{token}":{"parameters":[{"name":"token","in":"path","required":true,"description":"The secret part of an automation's `hookUrl`.","schema":{"type":"string"}}],"post":{"tags":["Automations"],"operationId":"triggerAutomation","x-status":"live","x-phase":"mvp","summary":"Incoming webhook. Starts the audit of the automation it belongs to","description":"The token in the path is the only credential: send no API key. The body is ignored. Answers `202` with the `runId`; when the audit has finished, the automation's Send webhook step delivers the result. `409 run_in_progress` carries the `runId` of the audit already waiting.","security":[],"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string"},"status":{"$ref":"#/components/schemas/RunStatus"},"automationId":{"type":"string"}}}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/api-keys":{"get":{"tags":["Keys"],"operationId":"listApiKeys","x-status":"live","x-phase":"mvp","summary":"List your keys (never the secret). Human session only","security":[{"session":[]}],"responses":{"200":{"description":"Keys (never the secret)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}}}},"post":{"tags":["Keys"],"operationId":"createApiKey","summary":"Create a key; it is shown once. Human session only","x-status":"live","x-phase":"mvp","security":[{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","scopes"],"properties":{"name":{"type":"string","maxLength":80},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/Scope"}},"expiresAt":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"Created. The key is shown once; only its hash is stored.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","properties":{"key":{"type":"string","examples":["mev_live_xxxxxxxx"]}}}]}}}}}}},"/api-keys/{keyId}":{"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"tags":["Keys"],"operationId":"revokeApiKey","summary":"Revoke a key. Human session only","x-status":"live","x-phase":"mvp","security":[{"session":[]}],"responses":{"204":{"description":"Revoked"}}}},"/usage":{"get":{"tags":["Usage"],"operationId":"getUsage","x-status":"live","x-phase":"poc","summary":"Audit credits used by this account","description":"Every check has a credit value (`GET /rules`). A finished audit costs the sum of its checks; an audit that could not start costs nothing. Days are UTC. No plan limit is enforced yet, so `limit` is `null`.","security":[{"apiKey":["audits:read"]},{"oauth2":["audits:read"]}],"responses":{"200":{"description":"Usage totals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/audit-scopes":{"get":{"tags":["Audit scopes"],"operationId":"listAuditScopes","x-status":"live","x-phase":"mvp","summary":"Built-in and saved audit scopes","description":"A scope is the list of checks one audit runs. Built in: `full` and one per area (`area:security`). Saved scopes have an id that starts with `scope_`.","security":[{"apiKey":["audits:read"]},{"oauth2":["audits:read"]}],"responses":{"200":{"description":"Scopes, built-in ones first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditScope"}}}}}}},"default":{"$ref":"#/components/responses/Problem"}}},"post":{"tags":["Audit scopes"],"operationId":"createAuditScope","x-status":"live","x-phase":"mvp","summary":"Save your own scope","description":"At most 20 per account. 409 `name_taken` or `scope_limit`.","security":[{"apiKey":["audits:write"]},{"oauth2":["audits:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AuditScopeWrite"},{"required":["name","ruleIds"]}]}}}},"responses":{"201":{"description":"Saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditScope"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/audit-scopes/{scopeId}":{"parameters":[{"name":"scopeId","in":"path","required":true,"schema":{"type":"string","pattern":"^scope_"}}],"get":{"tags":["Audit scopes"],"operationId":"getAuditScope","x-status":"live","x-phase":"mvp","summary":"One saved scope","security":[{"apiKey":["audits:read"]},{"oauth2":["audits:read"]}],"responses":{"200":{"description":"Scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditScope"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"patch":{"tags":["Audit scopes"],"operationId":"updateAuditScope","x-status":"live","x-phase":"mvp","summary":"Rename a saved scope or change its checks","description":"Audits already started keep the checks they were started with.","security":[{"apiKey":["audits:write"]},{"oauth2":["audits:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditScopeWrite"}}}},"responses":{"200":{"description":"Scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditScope"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"delete":{"tags":["Audit scopes"],"operationId":"deleteAuditScope","x-status":"live","x-phase":"mvp","summary":"Remove a saved scope","security":[{"apiKey":["audits:write"]},{"oauth2":["audits:write"]}],"responses":{"204":{"description":"Removed"},"default":{"$ref":"#/components/responses/Problem"}}}},"/plans":{"get":{"tags":["Billing"],"operationId":"listPlans","x-status":"live","x-phase":"mvp","summary":"The plans, their prices in USD and their limits","description":"Public. Free includes the REST API and API keys. `checkoutAvailable` is false until payments are open; plans and limits apply anyway.","security":[],"responses":{"200":{"description":"Plans","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanList"}}}}}}},"/billing":{"get":{"tags":["Billing"],"operationId":"getBilling","x-status":"live","x-phase":"mvp","x-mcp-tool":"get_billing","summary":"Your plan, this period's usage and your spend cap","description":"Any valid API key may read it. Runs that count are the runs of the billing period that did not fail. Above the included runs, a paid plan charges per run until the monthly spend cap.","security":[{"apiKey":[]},{"oauth2":[]}],"responses":{"200":{"description":"Billing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Billing"}}}},"default":{"$ref":"#/components/responses/Problem"}}},"patch":{"tags":["Billing"],"operationId":"updateBilling","x-status":"live","x-phase":"mvp","summary":"Set the monthly spend cap (signed-in session only)","description":"`spendCapCents` is the most usage above the included runs that one period may cost, 0 to 100000 (USD cents). 0 means no runs above the included ones. API keys get `403 session_required`.","security":[{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"spendCapCents":{"type":"integer","minimum":0,"maximum":100000},"extraSites":{"type":"integer","minimum":0,"maximum":200,"description":"Sites bought on top of a paid plan's, billed per site and month. `403 plan_limit` on Free, `409 sites_in_use` below the sites in use."}}}}}},"responses":{"200":{"description":"Billing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Billing"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/billing/checkout":{"post":{"tags":["Billing"],"operationId":"startCheckout","x-status":"live","x-phase":"mvp","summary":"Start a checkout for Starter, Pro or Ultra (session only)","description":"Answers a URL to send the person to (a Stripe-hosted page once payments are open). `interval` is `month` (default) or `year`; a year costs ten months. There is no trial: the first payment can be refunded on request within 14 days, bought credits excluded. An account that already has a plan gets `409 already_subscribed` and uses the portal. `503 billing_unavailable` until payments are open.","security":[{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan"],"properties":{"plan":{"type":"string","enum":["starter","pro","ultra"]},"interval":{"type":"string","enum":["month","year"],"default":"month"}}}}}},"responses":{"200":{"description":"Checkout page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedirectUrl"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/billing/purchases":{"post":{"tags":["Billing"],"operationId":"buyOneTimeAudit","x-status":"live","x-phase":"mvp","summary":"Buy the one-time deep audit for a site (session only)","description":"A plan is the monthly monitoring; a deep audit is bought separately, per site, on any plan. `deep-audit` buys one deep audit of one verified site, to be started within 30 days. It does not use the monthly credits; a run that fails goes back to the purchase. A re-audit after the fixes is recommended: every further deep audit of the same site costs 30% less (`GET /plans`, `oneTime`; the sites it applies to are `deepAuditFollowUpSites` in `GET /billing`). Answers a URL to send the person to (a Stripe-hosted page once payments are open). The site must be verified first (`403 verification_required`). `409 pass_active` while the site has a bought audit that was not started yet; `503 billing_unavailable` until payments are open. What an account holds is in `GET /billing` (`deepAuditPasses`).","security":[{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product","siteId"],"properties":{"product":{"type":"string","enum":["deep-audit"]},"siteId":{"type":"string"}}}}}},"responses":{"200":{"description":"Checkout page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedirectUrl"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/billing/portal":{"post":{"tags":["Billing"],"operationId":"openBillingPortal","x-status":"live","x-phase":"mvp","summary":"Open the Stripe customer portal (session only)","description":"Card, invoices, plan change and cancellation, on Stripe's page. `409 no_billing_account` before a first checkout.","security":[{"session":[]}],"responses":{"200":{"description":"Portal page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedirectUrl"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/problem-reports":{"get":{"tags":["Support"],"operationId":"listProblemReports","x-status":"live","x-phase":"mvp","summary":"Problems you reported, newest first","security":[{"apiKey":[]},{"session":[]}],"responses":{"200":{"description":"Reports","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProblemReport"}}}}}}},"default":{"$ref":"#/components/responses/Problem"}}},"post":{"tags":["Support"],"operationId":"createProblemReport","x-status":"live","x-phase":"mvp","summary":"Report a problem to the Metricevo team","description":"The team reads reports in the admin console. At most 10 a day.","security":[{"apiKey":[]},{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemReportCreate"}}}},"responses":{"201":{"description":"Received","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemReport"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/openapi.json":{"get":{"tags":["Meta"],"operationId":"getOpenApi","summary":"This contract as JSON (live operations only)","x-status":"live","x-phase":"poc","security":[],"responses":{"200":{"description":"This contract","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Workspace API key, `mev_live_` or `mev_test_` prefix. Only its SHA-256 is stored."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE, for MCP clients and partner apps.","flows":{"authorizationCode":{"authorizationUrl":"https://api.metricevo.com/oauth/authorize","tokenUrl":"https://api.metricevo.com/oauth/token","scopes":{"sites:read":"Read sites and priority pages","sites:write":"Add, change, remove and verify sites","audits:read":"Read runs, observations, findings, fix cards","audits:write":"Start and cancel runs, claim fixes","evidence:read":"Read redacted evidence","webhooks:manage":"Manage webhooks","events:read":"Read the event log","usage:read":"Read usage"}}}},"session":{"type":"apiKey","in":"cookie","name":"__Host-metricevo_session","description":"Web UI session (see docs/auth.md). Required for key management."}},"parameters":{"Cursor":{"name":"cursor","in":"query","schema":{"type":"string"}},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"SiteId":{"name":"siteId","in":"path","required":true,"schema":{"type":"string","pattern":"^site_"}},"RunId":{"name":"runId","in":"path","required":true,"schema":{"type":"string","pattern":"^run_"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":255}},"IdempotencyKeyRequired":{"name":"Idempotency-Key","in":"header","required":true,"description":"Same key within 24 h returns the same response; a different body returns 409.","schema":{"type":"string","maxLength":255}}},"responses":{"Problem":{"description":"RFC 9457 problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"PlanLimits":{"type":"object","properties":{"sites":{"type":"integer"},"creditsPerPeriod":{"type":"integer","description":"Audit credits included per billing period. A run costs the credits of its checks (full passive audit 48, full deep 75)."},"overageCentsPer1000Credits":{"type":["integer","null"],"description":"USD cents per 1","000 credits above the included ones; null means none (the plan stops at its credits)":null},"schedules":{"type":"array","items":{"type":"string","enum":["none","weekly","monthly"]}},"deepAudits":{"type":"boolean","description":"Deep audits on a verified site within the plan's credits. False on every plan while the one-time audits are on sale (now): `level: deep` answers 403 `plan_limit` unless a deep audit was bought for the site (`POST /billing/purchases`)."},"savedScopes":{"type":"integer","description":"Saved scopes of the account's own"},"automations":{"type":"integer","description":"Fair-use cap on automations"},"historyDays":{"type":"integer"},"apiPerMinute":{"type":"integer"},"apiWrite":{"type":"boolean","description":"API keys may write. Free: read-only; a write with a key answers `403 plan_limit`."},"extraSiteCentsPerMonth":{"type":["integer","null"],"description":"Price of one extra site a month in USD cents; null means none can be bought"}}},"Plan":{"type":"object","properties":{"id":{"type":"string","enum":["free","starter","pro","ultra","enterprise"]},"name":{"type":"string"},"priceCents":{"type":["integer","null"],"description":"Monthly base price in USD cents; null is a custom quote"},"priceCentsYearly":{"type":["integer","null"],"description":"Price of a year paid at once in USD cents; null means monthly only or custom"},"priceLabel":{"type":"string"},"currency":{"type":"string","const":"usd"},"interval":{"type":"string","const":"month"},"summary":{"type":"string"},"selfServe":{"type":"boolean"},"limits":{"$ref":"#/components/schemas/PlanLimits"},"features":{"type":"array","items":{"type":"string"}}}},"PlanList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Plan"}},"oneTime":{"type":"array","description":"One-time purchases, bought with `POST /billing/purchases`. Empty when they are not on sale.","items":{"type":"object","properties":{"id":{"type":"string","enum":["deep-audit"]},"name":{"type":"string"},"priceCents":{"type":"integer"},"priceLabel":{"type":"string"},"currency":{"type":"string"},"followUpPercentOff":{"type":"integer","description":"Discount on every further deep audit of a site that had one."},"followUpPriceCents":{"type":"integer","description":"Price of a further deep audit of the same site."},"runs":{"type":"integer","description":"Deep audits of the site in one purchase"},"validDays":{"type":"integer","description":"Days from the purchase in which the audit can be started"},"summary":{"type":"string"},"available":{"type":"boolean","description":"False until this product can be paid for."}}}},"trialDays":{"type":"integer","description":"0: no trial."},"moneyBackDays":{"type":"integer","description":"Refund on request within this many days of the first payment"},"earlyAccess":{"type":"object","properties":{"percentOff":{"type":"integer"},"months":{"type":"integer"},"active":{"type":"boolean"}}},"mode":{"type":"string","enum":["off","mock","stripe"],"description":"`mock`: test mode, a plan is switched on without Stripe (UAT and previews only)."},"checkoutAvailable":{"type":"boolean"}}},"Billing":{"type":"object","properties":{"plan":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"status":{"type":"string","description":"free, trialing, active, past_due or manual"},"cancelAtPeriodEnd":{"type":"boolean"},"trial":{"type":"object","properties":{"endsAt":{"type":["string","null"],"format":"date-time"},"available":{"type":"boolean"},"days":{"type":"integer"}}},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"usage":{"type":"object","properties":{"sites":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":"integer"}}},"credits":{"type":"object","properties":{"used":{"type":"integer"},"included":{"type":"integer"}}},"automations":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":"integer"}}},"extraSites":{"type":"object","properties":{"bought":{"type":"integer"},"centsPerMonth":{"type":["integer","null"]},"amountCents":{"type":"integer"}}},"overage":{"type":"object","properties":{"credits":{"type":"integer"},"amountCents":{"type":"integer"}}}}},"deepAuditPasses":{"type":"array","description":"Bought deep audits that were not started yet (`POST /billing/purchases`).","items":{"type":"object","properties":{"id":{"type":"string"},"siteId":{"type":"string"},"runsLeft":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"}}}},"deepAuditFollowUpSites":{"type":"array","items":{"type":"string"},"description":"Ids of the sites that had a deep audit bought; the next one costs less there."},"oneTimeAudits":{"type":"boolean","description":"The one-time deep audit can be bought now."},"spendCapCents":{"type":"integer"},"limits":{"$ref":"#/components/schemas/PlanLimits"},"mode":{"type":"string","enum":["off","mock","stripe"]},"checkoutAvailable":{"type":"boolean"},"portalAvailable":{"type":"boolean"}}},"RedirectUrl":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}},"Page":{"type":"object","properties":{"nextCursor":{"type":["string","null"]}}},"Problem":{"type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string","examples":["url_policy_denied","site_not_verified","idempotency_conflict","quota_exceeded","credit_limit_reached","spend_cap_reached","sites_in_use","not_found","invalid_request","unauthorized","invalid_api_key","insufficient_scope","developer_mode_required","idempotency_key_required","run_in_progress","site_exists","rate_limited"]},"requestId":{"type":"string"}}},"Area":{"type":"string","enum":["availability","security","email","performance","marketing","accessibility","privacy","technology","exposure"]},"RunStatus":{"type":"string","enum":["queued","running","succeeded","partial","failed"]},"ObservationStatus":{"type":"string","enum":["pass","fail","no_data","not_tested","failed"],"description":"`failed` means the measurement failed, not the site."},"Severity":{"type":"string","enum":["info","low","medium","high"]},"Confidence":{"type":"string","enum":["low","medium","high"]},"ChangeKind":{"type":"string","enum":["improved","regressed","unchanged","no_data"]},"TriggerType":{"type":"string","enum":["manual","scheduled","api","ci"]},"FindingState":{"type":"string","enum":["open","fix_claimed","verified","dismissed"]},"Scope":{"type":"string","enum":["sites:read","sites:write","audits:read","audits:write","evidence:read","webhooks:manage","events:read","usage:read"]},"Labels":{"type":"object","description":"Free key-value pairs, e.g. release, pipeline, NeoLoad test ID, Jira key.","maxProperties":20,"additionalProperties":{"type":"string","maxLength":200}},"SiteCreate":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"name":{"type":"string","maxLength":120},"stack":{"type":"string"},"schedule":{"$ref":"#/components/schemas/ScheduleInput"},"labels":{"$ref":"#/components/schemas/Labels"}}},"ScheduleInput":{"type":"object","description":"Recurring audit. The first run of a new schedule is one period from now.","required":["frequency"],"properties":{"frequency":{"type":"string","enum":["none","weekly","monthly"]}}},"Schedule":{"type":"object","properties":{"frequency":{"type":"string","enum":["none","weekly","monthly"]},"nextRunAt":{"type":["string","null"],"format":"date-time"}}},"Site":{"type":"object","required":["id","origin","verification"],"properties":{"id":{"type":"string","examples":["site_01JC9Z0000000000000000000"]},"origin":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri","description":"The address an audit reads."},"name":{"type":"string"},"schedule":{"$ref":"#/components/schemas/Schedule"},"lastRun":{"description":"Status and per-area counts of the latest audit.","oneOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/RunStatus"},"finishedAt":{"type":["string","null"],"format":"date-time"},"summary":{"type":"array","items":{"$ref":"#/components/schemas/AreaSummary"}}}},{"type":"null"}]},"stack":{"type":["string","null"]},"verification":{"$ref":"#/components/schemas/Verification"},"lastRunId":{"type":["string","null"]},"openFindings":{"type":"integer"},"labels":{"$ref":"#/components/schemas/Labels"},"createdAt":{"type":"string","format":"date-time"}}},"Verification":{"type":"object","properties":{"status":{"type":"string","enum":["unverified","verified","failed"],"description":"`failed`: the last check did not find the proof."},"method":{"type":["string","null"],"enum":["dns_txt","file",null]},"verifiedAt":{"type":["string","null"],"format":"date-time"},"checkedAt":{"type":["string","null"],"format":"date-time"}}},"ReportEmail":{"type":"object","properties":{"owner":{"type":"boolean","description":"The report goes to the address of the account."},"recipients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"addedAt":{"type":["string","null"],"format":"date-time"}}}},"recipientLimit":{"type":"integer"},"recipientsAllowed":{"type":"boolean","description":"True on a verified site. While false, no recipient can be added and the listed ones get no mail."},"lastSentAt":{"type":["string","null"],"format":"date-time"}}},"VerificationDetail":{"allOf":[{"$ref":"#/components/schemas/Verification"},{"type":"object","properties":{"unlocks":{"type":"array","description":"Audit levels a verified site can run.","items":{"$ref":"#/components/schemas/AuditLevel"}},"instructions":{"type":"object","properties":{"dns_txt":{"type":"object","properties":{"type":{"type":"string","examples":["TXT"]},"name":{"type":"string","examples":["_metricevo.example.com"]},"value":{"type":"string"}}},"file":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"content":{"type":"string"}}}}}}}]},"AuditLevel":{"type":"string","enum":["passive","deep"],"description":"`passive` reads what every visitor sees and runs on any public site. `deep` adds requests a visitor would not make (for example files that should not be public) and runs only on a verified site."},"RankedPage":{"type":"object","properties":{"path":{"type":"string"},"title":{"type":"string"},"score":{"type":"number","minimum":0,"maximum":100},"tier":{"type":"string","enum":["high","medium","low"]},"deepAudit":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}}}},"Profile":{"type":"object","properties":{"id":{"type":"string","examples":["prof_mobile_v1"]},"version":{"type":"string"},"device":{"type":"string","enum":["mobile","desktop"]},"labRuns":{"type":"integer","default":3},"ruleSetVersion":{"type":"string"}}},"AuditRunCreate":{"type":"object","required":["siteId"],"properties":{"siteId":{"type":"string"},"level":{"allOf":[{"$ref":"#/components/schemas/AuditLevel"}],"default":"passive","description":"`deep` answers 403 `verification_required` unless the site is verified."},"scope":{"type":"string","default":"full","description":"Which checks to run: `full`, `area:<area>` or the id of a saved scope (`GET /audit-scopes`). A passive audit runs the passive checks of the scope; if there are none, 400 `empty_scope`.","examples":["full","area:availability"]},"ruleIds":{"type":"array","minItems":1,"description":"An own selection of checks for this one run, without saving a scope: check ids from `GET /rules`. Send either `scope` or `ruleIds`, not both (400 `invalid_request`). The run reports the scope `custom`. A passive audit runs the passive checks of the selection; if there are none, 400 `empty_scope`.","items":{"type":"string"},"examples":[["email.spf","email.dmarc"]]},"urls":{"type":"array","description":"Defaults to the site's deep-audit pages.","maxItems":20,"items":{"type":"string","format":"uri"}},"profileId":{"type":"string","default":"prof_mobile_v1"},"areas":{"type":"array","items":{"$ref":"#/components/schemas/Area"}},"scheduledFor":{"type":"string","format":"date-time","description":"Start no earlier than this time (within 90 days). Omit to start now."},"baseline":{"description":"`previous` (default), `none`, or a run ID to compare with.","type":"string"},"labels":{"$ref":"#/components/schemas/Labels"}}},"RuntimeMetrics":{"type":"object","properties":{"durationMs":{"type":"integer"},"subrequests":{"type":"integer"},"psiCalls":{"type":"integer"},"cruxCalls":{"type":"integer"},"browserContextRuns":{"type":"integer"},"retries":{"type":"integer"}}},"AreaSummary":{"type":"object","properties":{"area":{"$ref":"#/components/schemas/Area"},"pass":{"type":"integer"},"fail":{"type":"integer"},"noData":{"type":"integer"},"notTested":{"type":"integer"},"regressed":{"type":"integer"},"improved":{"type":"integer"}}},"AuditRun":{"type":"object","required":["id","siteId","status","triggerType","profileVersion"],"properties":{"id":{"type":"string"},"siteId":{"type":"string"},"requestedUrl":{"type":"string","format":"uri"},"resolvedUrl":{"type":["string","null"],"format":"uri"},"scheduledFor":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"errorCode":{"type":["string","null"],"description":"Set when `status` is `failed`, for example `url_policy_denied`, or `verification_lost` when the ownership proof of a deep audit is gone."},"startedAt":{"type":["string","null"],"format":"date-time"},"finishedAt":{"type":["string","null"],"format":"date-time"},"status":{"$ref":"#/components/schemas/RunStatus"},"triggerType":{"$ref":"#/components/schemas/TriggerType"},"profileVersion":{"type":"string"},"level":{"$ref":"#/components/schemas/AuditLevel"},"scope":{"type":"object","description":"The scope as it was when the audit was started.","properties":{"id":{"type":"string"},"name":{"type":"string"},"checks":{"type":"integer"}}},"estimatedCredits":{"type":"integer","description":"The sum of the credits of the checks in this audit."},"credits":{"type":["integer","null"],"description":"Credits booked when the audit finished. 0 when it could not start; `null` while it runs."},"previousRunId":{"type":["string","null"]},"runtimeMetrics":{"oneOf":[{"$ref":"#/components/schemas/RuntimeMetrics"},{"type":"null"}]},"summary":{"type":"array","items":{"$ref":"#/components/schemas/AreaSummary"}},"labels":{"$ref":"#/components/schemas/Labels"},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"Observation":{"type":"object","required":["id","auditRunId","area","ruleId","status","severity","confidence"],"properties":{"id":{"type":"string"},"auditRunId":{"type":"string"},"url":{"type":"string","format":"uri"},"area":{"$ref":"#/components/schemas/Area"},"ruleId":{"type":"string"},"ruleVersion":{"type":"string"},"status":{"$ref":"#/components/schemas/ObservationStatus"},"severity":{"$ref":"#/components/schemas/Severity"},"confidence":{"$ref":"#/components/schemas/Confidence"},"summary":{"type":"string"},"evidenceRefs":{"type":"array","items":{"type":"string"}},"rawValue":{"type":["string","number","null"]},"unit":{"type":["string","null"]},"compareAs":{"type":"string","enum":["status","metric","score"]},"previousStatus":{"oneOf":[{"$ref":"#/components/schemas/ObservationStatus"},{"type":"null"}]},"previousValue":{"type":["string","number","null"]},"noise":{"type":["number","null"],"description":"Noise band for the metric; a change inside it is `unchanged`."},"change":{"$ref":"#/components/schemas/ChangeKind"},"createdAt":{"type":"string","format":"date-time"}}},"Comparison":{"type":"object","properties":{"runId":{"type":"string"},"baseRunId":{"type":["string","null"]},"improved":{"type":"integer"},"regressed":{"type":"integer"},"unchanged":{"type":"integer"},"noData":{"type":"integer"},"changes":{"type":"array","items":{"$ref":"#/components/schemas/Observation"}}}},"Evidence":{"type":"object","properties":{"id":{"type":"string"},"auditRunId":{"type":"string"},"type":{"type":"string","enum":["psi_json","crux_json","http_header","html_extract","cookie_snapshot","request_log","note"]},"label":{"type":"string"},"contentHash":{"type":"string"},"retentionUntil":{"type":"string","format":"date-time"},"redactionStatus":{"type":"string","enum":["redacted","not_applicable","pending"]}}},"Finding":{"type":"object","properties":{"id":{"type":"string"},"siteId":{"type":"string"},"ruleId":{"type":"string"},"area":{"$ref":"#/components/schemas/Area"},"severity":{"$ref":"#/components/schemas/Severity"},"state":{"$ref":"#/components/schemas/FindingState"},"firstSeenRunId":{"type":"string"},"lastSeenRunId":{"type":"string"},"verifiedByRunId":{"type":["string","null"]},"owner":{"type":["string","null"]},"note":{"type":["string","null"]}}},"Rule":{"type":"object","properties":{"id":{"type":"string","examples":["perf.lcp","marketing.canonical","privacy.tracker_before_consent"]},"version":{"type":"string"},"area":{"$ref":"#/components/schemas/Area"},"title":{"type":"string"},"whyItMatters":{"type":"string"},"defaultSeverity":{"$ref":"#/components/schemas/Severity"},"level":{"$ref":"#/components/schemas/AuditLevel"},"credits":{"type":"integer","description":"What running this check costs: 1 when it is read from the page that is fetched anyway, 2 when it needs its own lookup or request, 3 to 5 for deep requests."}}},"FixCard":{"type":"object","properties":{"ruleId":{"type":"string"},"stack":{"type":"string"},"stackVersion":{"type":"string"},"whyItMatters":{"type":"string"},"priority":{"$ref":"#/components/schemas/Severity"},"confidence":{"$ref":"#/components/schemas/Confidence"},"ownerRole":{"type":"string"},"whereToFix":{"type":"string"},"steps":{"type":"array","items":{"type":"string"}},"risk":{"type":"string"},"rollback":{"type":"string"},"verification":{"type":"string"}}},"RunExport":{"type":"object","required":["schemaVersion","run","observations"],"properties":{"schemaVersion":{"type":"string","examples":["2026-11-11"]},"run":{"$ref":"#/components/schemas/AuditRun"},"observations":{"type":"array","items":{"$ref":"#/components/schemas/Observation"}},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/Evidence"}}}},"WebhookCreate":{"type":"object","required":["url","eventTypes"],"properties":{"url":{"type":"string","format":"uri"},"eventTypes":{"type":"array","items":{"type":"string","examples":["com.metricevo.audit_run.completed.v1"]}},"description":{"type":"string"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"eventTypes":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","disabled"]},"createdAt":{"type":"string","format":"date-time"}}},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"eventId":{"type":"string"},"attempt":{"type":"integer"},"responseStatus":{"type":["integer","null"]},"deliveredAt":{"type":["string","null"],"format":"date-time"},"nextAttemptAt":{"type":["string","null"],"format":"date-time"}}},"Event":{"type":"object","description":"CloudEvents 1.0, thin payload (IDs and summary only).","required":["specversion","id","source","type","time"],"properties":{"specversion":{"type":"string","const":"1.0"},"id":{"type":"string"},"source":{"type":"string","examples":["/workspaces/ws_01JC9Z"]},"type":{"type":"string","enum":["com.metricevo.audit_run.queued.v1","com.metricevo.audit_run.completed.v1","com.metricevo.audit_run.failed.v1","com.metricevo.observation.regressed.v1","com.metricevo.finding.opened.v1","com.metricevo.finding.verified.v1","com.metricevo.privacy.tracker_before_consent.v1","com.metricevo.site.verification_changed.v1"]},"subject":{"type":"string"},"time":{"type":"string","format":"date-time"},"datacontenttype":{"type":"string","const":"application/json"},"data":{"type":"object"}}},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string","examples":["mev_live_ab12"]},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/Scope"}},"expiresAt":{"type":["string","null"],"format":"date-time"},"lastUsedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"ProblemReportCreate":{"type":"object","required":["category","message"],"properties":{"category":{"type":"string","enum":["bug","wrong_result","question","other"]},"message":{"type":"string","minLength":10,"maxLength":2000},"page":{"type":"string","description":"The app path the problem was seen on."},"runId":{"type":"string","description":"One of your audit runs","if the report is about it.":null}}},"AutomationNode":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","maxLength":40,"examples":["trigger"]},"type":{"type":"string","enum":["trigger.webhook","trigger.audit_finished","action.run_audit","action.send_webhook"]},"x":{"type":"integer","description":"Position on the canvas."},"y":{"type":"integer"},"config":{"type":"object","description":"`siteId` on `action.run_audit` and `trigger.audit_finished`; `url` (https, public) on `action.send_webhook`.","properties":{"siteId":{"type":"string"},"url":{"type":"string","format":"uri"}}}}},"AutomationGraph":{"type":"object","required":["nodes","edges"],"description":"One trigger and its actions, connected into one chain.","properties":{"nodes":{"type":"array","maxItems":6,"items":{"$ref":"#/components/schemas/AutomationNode"}},"edges":{"type":"array","items":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"}}}}}},"AutomationCreate":{"type":"object","required":["name","graph"],"properties":{"name":{"type":"string","maxLength":80},"enabled":{"type":"boolean","default":true},"graph":{"$ref":"#/components/schemas/AutomationGraph"}}},"Automation":{"type":"object","properties":{"id":{"type":"string","examples":["aut_01JC9Z0000000000000000000"]},"name":{"type":"string"},"enabled":{"type":"boolean"},"trigger":{"type":"string","enum":["webhook","audit_finished"]},"siteId":{"type":"string"},"graph":{"$ref":"#/components/schemas/AutomationGraph"},"hookUrl":{"type":"string","format":"uri","description":"The incoming webhook address. Present only when it was just created or replaced."},"hookPrefix":{"type":["string","null"],"description":"The first characters of the incoming token."},"deliverUrl":{"type":["string","null"],"format":"uri"},"signingSecret":{"type":["string","null"],"description":"Verifies `Metricevo-Signature` on outgoing webhooks (HMAC-SHA256 of `t.body`)."},"lastTriggeredAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"AutomationEvent":{"type":"object","properties":{"id":{"type":"string"},"runId":{"type":["string","null"]},"kind":{"type":"string","enum":["triggered","delivered","delivery_failed"]},"httpStatus":{"type":["integer","null"]},"detail":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"ProblemReport":{"type":"object","properties":{"id":{"type":"string","examples":["rep_01JC9Z0000000000000000000"]},"category":{"type":"string"},"message":{"type":"string"},"page":{"type":["string","null"]},"runId":{"type":["string","null"]},"status":{"type":"string","enum":["open","in_progress","closed"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"UsageTotal":{"type":"object","properties":{"credits":{"type":"integer"},"runs":{"type":"integer","description":"Finished audits that cost credits."}}},"Usage":{"type":"object","properties":{"limit":{"type":["integer","null"],"description":"Credits included in the account's plan per billing period (Free 250, Pro 5,000). A run that would go over is refused on Free (`credit_limit_reached`) and billed as overage on a paid plan up to the spend cap."},"today":{"allOf":[{"$ref":"#/components/schemas/UsageTotal"},{"properties":{"day":{"type":"string","format":"date"}}}]},"thisMonth":{"allOf":[{"$ref":"#/components/schemas/UsageTotal"},{"properties":{"month":{"type":"string","examples":["2026-11"]}}}]},"months":{"type":"array","description":"The last 90 days by month, newest first.","items":{"allOf":[{"$ref":"#/components/schemas/UsageTotal"},{"properties":{"month":{"type":"string"}}}]}},"days":{"type":"array","description":"Days with usage, newest first, at most 31.","items":{"allOf":[{"$ref":"#/components/schemas/UsageTotal"},{"properties":{"day":{"type":"string","format":"date"}}}]}}}},"AuditScope":{"type":"object","properties":{"id":{"type":"string","description":"`full`, `area:<area>` or `scope_…`. Send it as `scope` to `startAudit`.","examples":["full","area:security","scope_01JD0000000000000000000000"]},"name":{"type":"string"},"builtIn":{"type":"boolean"},"ruleIds":{"type":"array","items":{"type":"string"}},"checks":{"type":"integer"},"credits":{"type":"object","description":"What one audit with this scope costs at each level.","properties":{"passive":{"type":"integer"},"deep":{"type":"integer"}}},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"AuditScopeWrite":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"ruleIds":{"type":"array","minItems":1,"description":"Check ids from `GET /rules`.","items":{"type":"string"}}}}}}}