CI endpoints

POST /api/ci/run

Triggers a new visual regression test or baseline capture.

Request

POST https://visualq.ai/api/ci/run
Content-Type: application/json
X-API-Key: your-api-key

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	Scenario labels to filter
`browsers`	`string[]`	No	Browsers: `"chromium"`, `"firefox"`, `"webkit"`
`commitSha`	`string`	No	Git commit SHA
`branch`	`string`	No	Git branch name
`prNumber`	`number`	No	PR number
`prUrl`	`string`	No	PR URL
`ciProvider`	`string`	No	CI system name (e.g., `"github-actions"`)
`jiraKey`	`string`	No	Jira issue key
`perfBudgets`	`object`	No	Performance budget thresholds (when `type: "perf"`). Keys: `lcp`, `fcp`, `cls`, `tbt`, `ttfb`, `score`

When environment is provided, the run targets that environment's base URL. The resolved environment is included in the response.

When using a project-scoped API key, the project field is optional — the key's associated project is used automatically.

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"
}

environmentId and environmentName are only present when an environment was specified in the request.

Errors

Status	Response
400	`{"error": "project is required (use the project slug)"}`
404	`{"error": "Project \"slug\" not found"}`

GET /api/ci/status/{runId}

Returns the current status and results of a test run.

Request

GET https://visualq.ai/api/ci/status/\{runId\}
X-API-Key: your-api-key

Response

{
  "runId": "run_abc123",
  "projectId": "proj_xyz",
  "status": "completed",
  "type": "test",
  "environmentId": "env_abc",
  "environmentName": "Staging",
  "duration": 12345,
  "summary": {
    "total": 10,
    "passed": 8,
    "failed": 2
  },
  "error": null
}

Field	Type	Description
`runId`	`string`	Run identifier
`projectId`	`string`	Project identifier
`status`	`string`	`"running"`, `"completed"`, or `"failed"`
`type`	`string`	`"vrt-test"`, `"baseline"`, `"perf-test"`, `"seo-test"`, or `"tracking-test"`
`environmentId`	`string \| undefined`	Environment identifier (when present on the run)
`environmentName`	`string \| undefined`	Environment name (when present on the run)
`duration`	`number`	Duration in milliseconds (when complete)
`summary`	`object \| null`	Comparison results
`error`	`string \| null`	Error message if failed
`perfScore`	`number \| undefined`	Performance score 0–100 (perf runs only)
`perfAvgLcp`	`number \| undefined`	Average LCP in ms (perf runs only)
`perfBudgetResult`	`string \| undefined`	`"pass"` or `"fail"` (perf runs with budgets)
`seoScore`	`number \| undefined`	SEO score 0–100 (SEO runs only)
`seoPassed`	`number \| undefined`	Number of passed SEO checks
`seoFailed`	`number \| undefined`	Number of failed SEO checks
`seoWarnings`	`number \| undefined`	Number of SEO warnings
`seoLighthouseScore`	`number \| undefined`	Lighthouse SEO score (SEO runs only)

Errors

Status	Response
404	`{"error": "Run not found"}`

GET /api/ci/projects

Lists all projects accessible with the current API key.

Request

GET https://visualq.ai/api/ci/projects
X-API-Key: your-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.

On this page