REST API

The Evaris backend exposes a small REST API; this page is a human-readable mirror of its OpenAPI spec. OperationIds here match the spec exactly.

Base URL

Your Evaris API origin: https://api.evarisai.com for the hosted service (http://localhost:8787 for local development). The SDK/CLI reads it from EVARIS_API_URL.

Authentication

Two schemes, mutually scoped (see Authentication):

• Bearer (project API token): for /v1/runs/*. Header: Authorization: Bearer <token>.
• Session cookie: for /v1/setup/* and the auth routes. Established by the web UI's sign-in flow; not usable from scripts.

/health and /version are unauthenticated.

Error format

All non-2xx responses use:

{ "error": "<human-readable message>" }

Runs

createRun: POST /v1/runs

Creates a run in created status. Requires a project API token.

Body:

{
  "project_id": "support-agent",
  "execution_mode": "external",
  "name": "optional-run-name",
  "tags": { "env": "staging" }
}

name and tags are optional (tags defaults to {}).

Responses: 201 Run · 401 Auth required · 404 Project not found.

createArtifactUpload: POST /v1/runs/{run_id}/artifacts/upload-url

Returns a pre-signed PUT target for one artifact.

Body:

{
  "type": "inspect_eval_log",
  "file_name": "task.eval",
  "content_type": "application/json",
  "size_bytes": 1234,
  "checksum_sha256": "<hex>"
}

Responses: 201 ArtifactUpload (artifact_id, upload_url, headers, expires_at) · 401 · 404 Run not found.

putArtifactUpload: PUT /v1/runs/{run_id}/artifact-uploads/{artifact_id}

Uploads raw bytes to the URL returned by createArtifactUpload. Body is application/octet-stream. The backend validates the body matches the upload target's checksum/size.

Responses: 204 Uploaded · 400 Body mismatch · 401 · 404 Upload target not found.

completeRun: POST /v1/runs/{run_id}/complete

Submits the RunManifest, enqueues ingestion. The manifest's run_id and project_id must match the existing run.

Responses: 200 Run (now in succeeded / ingested_with_warnings / failed) · 400 Manifest mismatch · 401 · 404 · 500 Failed to enqueue ingest job.

getRun: GET /v1/runs/{run_id}

Responses: 200 Run · 401 · 404.

deleteRun: DELETE /v1/runs/{run_id}

Responses: 204 Deleted · 401 · 404 · 409 Run cannot be deleted in its current state (only created runs are deletable).

listRuns: GET /v1/runs

Paginated list of runs for a project, newest first.

Note: the route exists in the spec and the web UI uses it, but the generated TypeScript SDK does not yet expose it (see SDK reference § Known gaps). REST callers may use it directly; SDK callers must wait for a regen. Query parameters (project id, cursor, limit) are defined in the spec's ListRunsQuerySchema.

Setup (session-gated)

These require a browser session and a trusted origin. Driven by the web UI, not by publishers.

bootstrapSetup: POST /v1/setup/bootstrap

Provisions the caller's tenant and default project if absent. Returns BootstrapSetupResponse (tenant, project, projects[]).

createProjectApiToken: POST /v1/setup/projects/{project_id}/api-tokens

Mints a project API token. Body: { "name"?: string }. The full token is returned exactly once; only the prefix is stored thereafter.

System

getHealth: GET /health

Unauthenticated. Returns { "status": "ok" }.

getVersion: GET /version

Unauthenticated. Returns { "name": "evaris-backend-service", "version": "<semver>" }.

Status codes summary