REST API

The VisualQ REST API lets you trigger test runs and check their status from any CI system.

Base URL

https://visualq.ai/api

Authentication

All CI endpoints require an API key in the X-API-Key header.

X-API-Key: your-api-key-here

Trigger a test run

`POST /api/ci/run`

Starts a new visual regression test or baseline capture.

Request body:

Field	Type	Required	Description
`project`	string	Yes	Project slug
`type`	string	No	`test` (default), `baseline`, `perf`, `seo`, or `tracking`
`environment`	string	No	Environment name or slug (e.g., `staging`)
`scenarios`	string[]	No	Filter to specific scenario labels
`browsers`	string[]	No	`chromium`, `firefox`, `webkit`
`commitSha`	string	No	Git commit SHA
`branch`	string	No	Git branch name
`prNumber`	number	No	Pull request number
`prUrl`	string	No	Pull request URL
`ciProvider`	string	No	CI system name
`jiraKey`	string	No	Jira issue key (e.g., `PROJ-123`)
`perfBudgets`	object	No	Performance budget thresholds (when `type: "perf"`). Keys: `lcp`, `fcp`, `cls`, `tbt`, `ttfb`, `score`

When environment is provided, scenarios are tested against that environment's base URL instead of the default. The value can be either the environment name (e.g., "Staging") or its slug (e.g., "staging").

Example request:

curl -X POST https://visualq.ai/api/ci/run \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VISUALQ_API_KEY" \
  -d '{
    "project": "my-website",
    "type": "test",
    "environment": "staging",
    "commitSha": "abc123",
    "branch": "feature/redesign",
    "prNumber": 42,
    "ciProvider": "github-actions"
  }'

Response (202 Accepted):

{
  "success": true,
  "runId": "run_abc123",
  "projectId": "proj_xyz",
  "type": "test",
  "environmentId": "env_abc",
  "environmentName": "Staging",
  "statusUrl": "/api/ci/status/run_abc123",
  "message": "VRT test started"
}

Check run status

`GET /api/ci/status/[runId]`

Returns the current status of a test run.

Response:

{
  "runId": "run_abc123",
  "projectId": "proj_xyz",
  "status": "completed",
  "type": "vrt-test",
  "duration": 12345,
  "summary": {
    "total": 5,
    "passed": 4,
    "failed": 1
  },
  "error": null
}

For performance runs (type: "perf"), the response also includes:

{
  "perfScore": 85,
  "perfAvgLcp": 1200,
  "perfBudgetResult": "pass"
}

For SEO runs (type: "seo"), the response also includes:

{
  "seoScore": 92,
  "seoPassed": 18,
  "seoFailed": 2,
  "seoWarnings": 3,
  "seoLighthouseScore": 88
}

Status values:

Status	Description
`running`	Test is in progress
`completed`	Finished successfully
`failed`	An error occurred

Type values in response:

Type	Description
`vrt-test`	Visual regression test
`baseline`	Baseline capture
`perf-test`	Performance test
`seo-test`	SEO audit
`tracking-test`	Tracking audit

List projects

`GET /api/ci/projects`

Returns a list of projects accessible with the current API key.

Response:

{
  "projects": [
    {
      "id": "proj_xyz",
      "name": "My Website",
      "slug": "my-website",
      "baseUrl": "https://example.com",
      "scenarioCount": 12
    }
  ],
  "count": 1
}

When using a project-scoped API key, the response contains only the single associated project.

Polling pattern

To wait for a run to complete, poll the status endpoint:

RUN_ID=$(curl -s -X POST https://visualq.ai/api/ci/run \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VISUALQ_API_KEY" \
  -d '{"project": "my-website"}' | jq -r '.runId')

while true; do
  STATUS=$(curl -s "https://visualq.ai/api/ci/status/$RUN_ID" \
    -H "X-API-Key: $VISUALQ_API_KEY" | jq -r '.status')
  
  if [ "$STATUS" != "running" ]; then
    echo "Run finished with status: $STATUS"
    break
  fi
  
  sleep 5
done

On this page