API reference

Anything you can do in the dashboard, you can do programmatically: test runs, reports, screenshots, and integration hooks.

Overview

The sarvaTest API follows REST conventions and returns JSON for every endpoint. The base URL is your workspace URL followed by /api/v1. All requests must be made over HTTPS.

https://<your-workspace>.sarvatest.com/api/v1/...

Authentication

Generate a token from Settings → API keys and pass it as a bearer header on every request:

GET /api/v1/runs
Host: acme.sarvatest.com
Authorization: Bearer sk_live_abc123...

Endpoints

List runs

GET /api/v1/runs

Returns recent test runs, paginated. Filter by status, branch, or commit to scope to specific results.

Trigger a run

POST /api/v1/runs

Trigger a new test run for a specific commit. Required body fields: branch, commit, test_pattern. Returns the new run's id so you can poll for status.

Get a run

GET /api/v1/runs/:id

Retrieve a single run with full test results, screenshots, and any visual-regression diffs.

Cancel a run

DELETE /api/v1/runs/:id

Cancel an in-progress run. Already-completed runs cannot be cancelled.

Rate limiting

The API allows 600 requests per minute per workspace. Headers returned on every response:

Header	Meaning
X-RateLimit-Limit	Your minute-wide quota.
X-RateLimit-Remaining	Requests left in the current window.
X-RateLimit-Reset	Unix timestamp when the window resets.

429 Too Many Requests means back off and retry after the Retry-After header.

Errors

{
  "error": {
    "code": "validation_failed",
    "message": "Field 'commit' is required.",
    "field": "commit"
  }
}