The API contract

One account model and one set of operations across the web app and CLI.

Read the machine-readable contract

The versioned API begins at /api/v1. The OpenAPI document is the reference for request fields and responses. Use it instead of reconstructing an endpoint from a screenshot or this overview.

Account operations accept an account session or a bearer credential issued through the device sign-in flow. Creating a report requires an account; existing public-link reports remain readable without signing in. Project and experiment data are owner-scoped.

Resource overview

Resource	Purpose
/reports	Create a public website audit; list account reports.
/reports/{id}	Read a public report or delete an owned report.
/reports/{id}/events	Read recorded run stages as JSONL; resume with ?after=SEQUENCE.
/reports/{id}/fixes	Read all observations with editorial priorities, evidence and an agent brief.
/projects	Create and list private projects.
/projects/{id}	Read, update, or delete an owned project.
/experiments	Create and list experiment records.
/experiments/{id}	Read a record, upload its immutable result, or delete it.
/telemetry	Submit or inspect account telemetry.
/usage	Read account usage and limits.
/account	Inspect the authenticated account and terms status.
/account/terms	Read or explicitly accept the current terms version.
/auth/device	Begin a device authorization request.
/auth/device/token	Poll an approved device request.
/auth/tokens	List host credential metadata.

Submit and read a website audit

Accept the current terms and authenticate with evx auth login. Save this request as audit.json:

{ "url": "https://example.com" }

Submit through the CLI, which supplies the saved host credential to POST /api/v1/reports:

evx api POST /reports --file audit.json

The response uses HTTP 202 when the audit has been accepted. This is an illustrative response shape, not a completed live report:

{
  "id": "00000000-0000-4000-8000-000000000001",
  "url": "/reports/00000000-0000-4000-8000-000000000001",
  "visibility": "public-link",
  "savedToAccount": true
}

Read GET /api/v1/reports/{id} to inspect status. It can be queued, running, completed, or failed. A completed run contains its report; a failed run contains an error. The CLI's --wait option handles polling.

The report's progress array records actual service stages and available counts. GET /api/v1/reports/{id}/events?after=2 returns a bounded JSONL snapshot after sequence 2; poll until X-Evx-Run-Status is completed or failed. These events have the report's public-link visibility. Older reports can have no events. Static runs do not include model trials or sandbox execution.

A project creation uses POST /api/v1/projects with name and an optional description. It returns HTTP 201 with the project's ID, normalized fields, and creation timestamp. Collection reads return items and nextCursor; pass a non-null cursor back as ?cursor=VALUE to read the next page.

Review terms before account writes

New account work and host credentials require explicit acceptance of the terms. Existing accounts are prompted too; earlier use is not recorded as agreement. Reads, exports and deletion remain available. New audits require a signed-in account and current terms acceptance.

Read evx api GET /account/terms. After reviewing the returned version and obtaining authority to agree for the account, save { "version": "2026-09-08", "accepted": true } to acceptance.json and send it using the command below. This example version must match the current response. Do not automatically accept on behalf of someone who has not authorized you.

evx api PUT /account/terms --file acceptance.json

A required agreement returns HTTP 428 with terms_required and review links. A stale version returns HTTP 409 with terms_version_changed; read and review the new terms before making a new acceptance request. Retrying the same current acceptance keeps its first timestamp. Browser users can review account terms. New CLI connections offer the same acceptance form inline at /connect, retaining the entered device code while you review the policy in a separate tab.

Handle errors as data

{ "error": { "code": "sign_in_required", "message": "Sign in to use your account data." }, "requestId": "00000000-0000-4000-8000-000000000001" }

Failures include a stable code, a readable message, and a request identifier. A rate-limited response can include retryAfterSeconds. Inspect the status and error code before retrying; changing credentials will not fix an invalid request.

Keep credentials in authorization headers. Do not put bearer tokens in URLs, which can become part of browser history or logs. See CLI authentication for host credential storage and revocation.