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

Pass your API key using the Authorization: Bearer header (recommended) or the legacy x-api-key header:

# Recommended
curl -H "Authorization: Bearer your_api_key_here" https://api.regressionbot.com/job/job_7x9kLm2p

# Legacy (also accepted)
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.

Example Request

curl -X POST "https://api.regressionbot.com/crawl" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "string",
    "autoApprove": false,
    "testOrigin": "string",
    "url": "string",
    "sitemapUrl": "string",
    "baseOrigin": "string",
    "devices": [
      "string"
    ],
    "paths": [
      {
        "path": "string",
        "label": "string"
      }
    ],
    "scans": [
      {
        "pattern": "string",
        "options": null
      }
    ],
    "masks": [
      "string"
    ],
    "concurrency": 0,
    "runContext": null
  }'

Request Body Schema

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

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.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.regressionbot.com/job/{jobId}"

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": [
        {
          "label": "string",
          "text": "string",
          "verdict": null
        }
      ],
      "verdict": null
    }
  ],
  "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.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.regressionbot.com/job/{jobId}/summary"

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,
  "intentAssessment": null,
  "runContext": null,
  "regressions": [
    {
      "url": "string",
      "variantName": "Desktop Chrome",
      "diffCount": 0,
      "baselineUrl": "string",
      "currentUrl": "string",
      "diffUrl": "string",
      "regressionbotSummary": [
        {
          "label": "string",
          "text": "string",
          "verdict": null
        }
      ],
      "verdict": null
    }
  ],
  "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.

Example Request

curl -X POST "https://api.regressionbot.com/approve" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "string"
  }'

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.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.regressionbot.com/projects"

Response Codes

200Projects list retrieved successfully

[
  {
    "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",
    "baselineVersion": "string"
  }
]

401Unauthorized

403Forbidden

get/project/{name}

Get project configuration

Retrieve the stored configuration for a named project.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.regressionbot.com/project/{name}"

Response Codes

200Project configuration retrieved successfully

{
  "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",
  "baselineVersion": "string"
}

401Unauthorized

403Forbidden

404Project not found

put/project/{name}

Update project configuration

Update the configuration settings for a named project. This invalidates baseline captures by bumping baselineVersion.

Example Request

curl -X PUT "https://api.regressionbot.com/project/{name}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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
  }'

Request Body Schema

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

Response Codes

200Project configuration updated and baselines invalidated successfully

{
  "message": "Project configuration updated and baselines invalidated successfully",
  "project": {
    "name": "string",
    "testOrigin": "string",
    "baseOrigin": "string",
    "sitemapUrl": "string",
    "baselineVersion": "string",
    "baselineInvalidatedAt": "string",
    "updatedAt": "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.

Example Request

curl -X POST "https://api.regressionbot.com/project/{name}/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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,
    "runContext": null
  }'

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,
  "runContext": null
}

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

post/ci/job/init

Initialize a client-driven visual regression job

Initiates a visual regression job when screenshots are captured locally (e.g. using the Playwright integration SDK). Sets up metadata and returns a jobId.

Example Request

curl -X POST "https://api.regressionbot.com/ci/job/init" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "string",
    "testOrigin": "string",
    "branch": "string",
    "commit": "string",
    "devices": [
      "string"
    ],
    "runContext": null
  }'

Request Body Schema

{
  "project": "string",
  "testOrigin": "string",
  "branch": "string",
  "commit": "string",
  "devices": [
    "string"
  ],
  "runContext": null
}

Response Codes

200Job initialized successfully

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000"
}

400Invalid input or validation failure

401Unauthorized

403Forbidden

post/ci/job/upload-url

Request a presigned URL to upload a screenshot

Generates a secure, short-lived S3 putObject signed URL for uploading a locally-captured screenshot.

Example Request

curl -X POST "https://api.regressionbot.com/ci/job/upload-url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "string",
    "url": "string",
    "variantName": "string"
  }'

Request Body Schema

{
  "jobId": "string",
  "url": "string",
  "variantName": "string"
}

Response Codes

200Presigned upload URL generated successfully

{
  "uploadUrl": "string",
  "currentKey": "string"
}

400Invalid input

401Unauthorized

403Forbidden

404Job not found

post/ci/job/finalize

Finalize a client-driven visual regression job

Instructs the server that all screenshots have been uploaded and triggers the parallel comparison flow in the cloud.

Example Request

curl -X POST "https://api.regressionbot.com/ci/job/finalize" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "string"
  }'

Request Body Schema

{
  "jobId": "string"
}

Response Codes

200Job finalized and comparison started

{
  "message": "Job execution finalized and comparison started",
  "jobId": "550e8400-e29b-41d4-a716-446655440000"
}

400Invalid input or state validation failure

401Unauthorized

403Forbidden

404Job not found