REST API Reference

Integrate RegressionBot with any programming language or automated CI system. All requests must target the standard gateway base URL:

https://api.regressionbot.com

🔑 Prerequisite: API Key RequiredAll REST requests require the authentication header to run successfully.

Get API Key →

Authentication Header

Include your authentication key in the x-api-key request header for every endpoint:

curl -H "x-api-key: your_api_key_here" https://api.regressionbot.com/job/job_7x9kLm2p

Endpoint Reference

post/crawl

Start a visual regression job

Triggers a new visual regression job for a single URL or a sitemap.

Request Body Schema

{
  "project": "string",
  "testOrigin": "string",
  "url": "string",
  "sitemapUrl": "string",
  "baseOrigin": "string",
  "devices": [
    "string"
  ],
  "paths": [
    {
      "path": "string",
      "label": "string"
    }
  ],
  "scans": [
    {
      "pattern": "string",
      "options": null
    }
  ],
  "masks": [
    "string"
  ],
  "concurrency": 0
}

Response Codes

200Job started successfully

{
  "message": "Visual regression job started",
  "jobId": "550e8400-e29b-41d4-a716-446655440000"
}

400Invalid input

500Internal server error

get/job/{jobId}

Get job status

Retrieve the current status and progress of a visual regression job.

Response Codes

200Job status retrieved successfully

{
  "jobId": "string",
  "status": "string",
  "summaryStatus": "string",
  "progress": {
    "total": 0,
    "completed": 0,
    "percent": "50.00"
  },
  "executionTime": 0,
  "results": [
    {
      "url": "string",
      "status": "string",
      "diffCount": 0,
      "diffPercentage": 0,
      "currentKey": "string",
      "baselineKey": "string",
      "diffKey": "string",
      "regressionbotSummary": "string"
    }
  ],
  "createdAt": "string"
}

404Job not found

get/job/{jobId}/summary

Get job summary with signed URLs

Retrieve a summary of the completed job, including pre-signed URLs for diff images.

Response Codes

200Job summary retrieved successfully

{
  "jobId": "string",
  "status": "string",
  "totalUrls": 0,
  "completedCount": 0,
  "overallScore": 98.5,
  "executionTime": 0,
  "regressionCount": 0,
  "matchCount": 0,
  "newBaselineCount": 0,
  "errorCount": 0,
  "regressions": [
    {
      "url": "string",
      "variantName": "Desktop Chrome",
      "diffCount": 0,
      "baselineUrl": "string",
      "currentUrl": "string",
      "diffUrl": "string",
      "regressionbotSummary": "string"
    }
  ],
  "matches": [
    {
      "url": "string",
      "variantName": "string",
      "baselineUrl": "string",
      "currentUrl": "string"
    }
  ],
  "newBaselines": [
    {
      "url": "string",
      "variantName": "string"
    }
  ],
  "errors": [
    {
      "url": "string",
      "errorMessage": "string"
    }
  ]
}

400Job not completed yet

404Job not found

post/approve

Approve job baselines

Promote the current screenshots of a job to be the new baselines.

Request Body Schema

{
  "jobId": "string"
}

Response Codes

200Baselines approved successfully

{
  "message": "Job baseline approved",
  "jobId": "string",
  "approvedUrlsCount": 0
}

404Job not found

get/projects

List all projects

Retrieve all saved project configurations for the authenticated organization.

Response Codes

200Projects list retrieved successfully

[
  {
    "orgId": "string",
    "name": "my-billing-app",
    "testOrigin": "https://staging.myapp.com",
    "baseOrigin": "https://myapp.com",
    "sitemapUrl": "https://staging.myapp.com/sitemap.xml",
    "paths": [
      {
        "path": "string",
        "label": "string"
      }
    ],
    "scans": [
      {
        "pattern": "string",
        "options": null
      }
    ],
    "devices": [
      "string"
    ],
    "masks": [
      "string"
    ],
    "concurrency": 0,
    "createdAt": "string",
    "updatedAt": "string",
    "lastRunAt": "string",
    "lastJobId": "string",
    "baselineInvalidatedAt": "string"
  }
]

401Unauthorized

403Forbidden

get/project/{name}

Get project configuration

Retrieve the stored configuration for a named project.

Response Codes

200Project configuration retrieved successfully

{
  "orgId": "string",
  "name": "my-billing-app",
  "testOrigin": "https://staging.myapp.com",
  "baseOrigin": "https://myapp.com",
  "sitemapUrl": "https://staging.myapp.com/sitemap.xml",
  "paths": [
    {
      "path": "string",
      "label": "string"
    }
  ],
  "scans": [
    {
      "pattern": "string",
      "options": null
    }
  ],
  "devices": [
    "string"
  ],
  "masks": [
    "string"
  ],
  "concurrency": 0,
  "createdAt": "string",
  "updatedAt": "string",
  "lastRunAt": "string",
  "lastJobId": "string",
  "baselineInvalidatedAt": "string"
}

401Unauthorized

403Forbidden

404Project not found

post/project/{name}/run

Run project visual regression job

Run a visual regression job using the saved project configuration, optionally overriding configuration parameters.

Request Body Schema

{
  "testOrigin": "string",
  "url": "string",
  "sitemapUrl": "string",
  "baseOrigin": "string",
  "devices": [
    "string"
  ],
  "paths": [
    {
      "path": "string",
      "label": "string"
    }
  ],
  "scans": [
    {
      "pattern": "string",
      "options": null
    }
  ],
  "masks": [
    "string"
  ],
  "concurrency": 0,
  "autoApprove": false
}

Response Codes

200Job started successfully

{
  "message": "Visual regression job started",
  "jobId": "550e8400-e29b-41d4-a716-446655440000"
}

400Invalid input or URL validation failure

401Unauthorized

403Forbidden

404Project not found