izridocs
Browse docs
Docs /reference/rest-api
Reference

REST API

Izri's HTTP surface is deliberately small. REST covers the things that must be plain HTTP — health checks, CI triggers, inbound webhooks, file serving — and everything else goes through tRPC.

For programmatic use, prefer the CLI or the MCP server. They wrap this surface and stay in step with it.

Authentication

Authorization: Bearer izri_xxxxxxxxxxxx

The API checks the izri_ prefix first and only then validates the token. Without the prefix the request falls through to cookie-session handling and returns an opaque 401. See API tokens.

Browser sessions use a cookie set by the auth flow; token auth takes precedence when both are present.

Endpoints

GET /health

Liveness. No authentication.

curl https://api.izri.ai/health

GET /api/test-runs/:runId/status

Current status of a test run.

curl -H "Authorization: Bearer $IZRI_API_TOKEN" \
     https://api.izri.ai/api/test-runs/01HK.../status

Returns one of PENDING, RUNNING, PASSED, FAILED, ERROR, CANCELLED. See verdicts and exit codes.

For polling, prefer izri run --watch — it already implements sane intervals and a timeout.

POST /api/ci/trigger/:projectId

Trigger a run from a CI system that isn't GitHub Actions.

curl -X POST \
     -H "Authorization: Bearer $IZRI_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"branch":"feat/x","commitSha":"abc123"}' \
     https://api.izri.ai/api/ci/trigger/01HK...

Requires tests:run. Returns the run identifier immediately; the run is asynchronous.

GET /files/*

Serves stored artifacts — visual snapshots, diffs, reports. Authenticated: these are your organization's artifacts, not public objects.

Inbound webhook receivers

These are endpoints Izri receives on. You don't call them; you configure a provider to.

Endpoint Sender
POST /api/webhooks/github-app GitHub App events
POST /api/webhooks/github/:projectId Per-project GitHub webhook
POST /api/webhooks/stripe Stripe billing events

For webhooks Izri sends you, see outbound webhooks.

Authentication routes

/api/auth/** is handled by the auth layer — OAuth callbacks, session management. Not intended for direct calls.

The GitHub OAuth callback must exactly match the configured app URL. A port mismatch produces a silent redirect loop rather than an error, and it is the most common self-hosting misconfiguration.

tRPC

Everything else is tRPC, mounted at /trpc/*, with the same bearer-token authentication.

The tRPC surface is typed end-to-end and changes with the product. Rather than documenting procedure signatures that would drift, use the clients that are versioned against it — the CLI and the MCP server.

Errors

Standard HTTP status codes.

Status Meaning
401 Missing, malformed, or invalid token. Check the izri_ prefix.
403 Authenticated, but the token lacks the required scope.
404 Not found — or the resource belongs to another organization.
402 The operation requires a higher plan.
429 Rate limited.

404 doubling as a cross-organization permission error is intentional: it avoids confirming that a resource exists to someone who can't access it. If you're sure an ID is valid and still get 404, verify the token belongs to the right organization.

Reading this with an agent? /docs/reference/rest-api.md serves the raw markdown.

Edit this page on GitHub →All docs