Project Configurations

In RegressionBot, a project serves as both a baseline namespace and a saved execution configuration. Once created, a project locks in its testing parameters — preventing baseline drift and ensuring that every run compares against the same set of pages, devices, and masks.

Projects operate in managed mode (where screenshots are stored as baselines and compared on subsequent runs) by default. They work the same way across all interfaces: the REST API, the Node.js SDK, and MCP agentic tools. The first run against a new project name creates the project and saves its configuration. Repeat runs can omit all parameters and load the saved configuration automatically.

Project Configuration Locking

Configuration locking applies exclusively to managed mode runs (where no baseOrigin is supplied and screenshots are stored as baselines for comparison on future runs). In live-vs-live mode (where baseOrigin is present), parameters are always accepted since there are no stored baselines to protect.

Baseline Invalidation & Rollback

When you need to update a project's parameters (for example, adding a new page path or a new device), the existing baselines are no longer compatible with the new configuration.

To update a project's configuration via the REST API, use PUT /project/{name}. This updates the stored config and invalidates existing baselines:

curl -X PUT https://api.regressionbot.com/project/my-project \
  -H "x-api-key: $REGRESSIONBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"testOrigin": "https://new-origin.com", "devices": ["Desktop Chrome"]}'

This triggers a baseline invalidation — because baselineVersion changes, the next run creates new baselines from scratch. All results on the next job will show isNewBaseline: true. Run the job a second time to begin detecting regressions.

REST API

Five dedicated endpoints let you manage and run projects: POST /project, GET /project/{name}, PUT /project/{name}, POST /project/{name}/run, and GET /projects.

Note: Projects are also created implicitly — the first POST /crawl or POST /project/{name}/run call with a new project name automatically creates the project and saves its configuration. There is no separate explicit creation step required.

curl https://api.regressionbot.com/projects \
  -H "x-api-key: YOUR_API_KEY"

[
  {
    "orgId": "org_abc123",
    "name": "my-billing-app",
    "testOrigin": "https://staging.myapp.com",
    "devices": ["Desktop Chrome", "iPhone 12"],
    "lastRunAt": "2024-06-01T10:00:00.000Z",
    "lastJobId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2024-05-01T09:00:00.000Z",
    "updatedAt": "2024-06-01T10:00:00.000Z"
  }
]

curl https://api.regressionbot.com/project/my-billing-app \
  -H "x-api-key: YOUR_API_KEY"

{
  "orgId": "org_abc123",
  "name": "my-billing-app",
  "testOrigin": "https://staging.myapp.com",
  "sitemapUrl": "https://staging.myapp.com/sitemap.xml",
  "paths": [
    { "path": "/invoice", "label": "Invoice Page" },
    { "path": "/settings" }
  ],
  "devices": ["Desktop Chrome", "iPhone 12"],
  "masks": [".ad-banner", "#cookie-notice"],
  "concurrency": 5,
  "createdAt": "2024-05-01T09:00:00.000Z",
  "updatedAt": "2024-06-01T10:00:00.000Z",
  "lastRunAt": "2024-06-01T10:00:00.000Z",
  "lastJobId": "550e8400-e29b-41d4-a716-446655440000"
}

curl -X POST https://api.regressionbot.com/project/my-billing-app/run \
  -H "x-api-key: YOUR_API_KEY"

curl -X POST https://api.regressionbot.com/project/my-billing-app/run \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "testOrigin": "https://pr-42.preview.myapp.com",
    "concurrency": 10
  }'

curl -X POST https://api.regressionbot.com/project/my-billing-app/run \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "autoApprove": true }'

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

How to Configure

curl -X POST https://api.regressionbot.com/crawl \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-billing-app",
    "testOrigin": "https://staging.myapp.com",
    "devices": ["Desktop Chrome", "iPhone 12"],
    "paths": [
      { "path": "/invoice" },
      { "path": "/settings" }
    ]
  }'

import { RegressionBot } from 'regressionbot';

const client = new RegressionBot(process.env.REGRESSIONBOT_API_KEY!);

const job = await client
  .test('https://staging.myapp.com')
  .forProject('my-billing-app')
  .on(['Desktop Chrome', 'iPhone 12'])
  .paths(['/invoice', '/settings'])
  .run();

# Loads the saved config for my-billing-app
curl -X POST https://api.regressionbot.com/project/my-billing-app/run \
  -H "x-api-key: YOUR_API_KEY"

# Also works: omit all params except project name
curl -X POST https://api.regressionbot.com/crawl \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "project": "my-billing-app" }'

import { RegressionBot } from 'regressionbot';

const client = new RegressionBot(process.env.REGRESSIONBOT_API_KEY!);

// No origin, devices, or paths — loads config from 'my-billing-app'.
const job = await client
  .forProject('my-billing-app')
  .run();

# .github/workflows/visual-regression.yml
name: Visual Regression Check

on:
  deployment_status:

jobs:
  visual-check:
    if: github.event.deployment_status.state == 'success' && github.event.deployment_status.environment == 'staging'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run visual regression
        env:
          REGRESSIONBOT_API_KEY: ${{ secrets.REGRESSIONBOT_API_KEY }}
        run: |
          # Start the job using the project's saved config
          RESPONSE=$(curl -s -X POST https://api.regressionbot.com/project/my-billing-app/run \
            -H "x-api-key: $REGRESSIONBOT_API_KEY")

          JOB_ID=$(echo $RESPONSE | jq -r '.jobId')
          if [ -z "$JOB_ID" ] || [ "$JOB_ID" = "null" ]; then
            echo "::error::Failed to start job: $RESPONSE"
            exit 1
          fi
          echo "Job started: $JOB_ID"

          # Poll until complete (max 10 minutes)
          STATUS=""
          for i in $(seq 1 60); do
            sleep 10
            STATUS=$(curl -s https://api.regressionbot.com/job/$JOB_ID \
              -H "x-api-key: $REGRESSIONBOT_API_KEY" | jq -r '.status')
            echo "Status: $STATUS"
            if [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "APPROVED" ] || [ "$STATUS" = "FAILED" ]; then
              break
            fi
          done

          if [ "$STATUS" = "FAILED" ]; then
            echo "::error::Visual regression job failed"
            exit 1
          fi

          if [ "$STATUS" != "COMPLETED" ] && [ "$STATUS" != "APPROVED" ]; then
            echo "::error::Job timed out after 10 minutes (last status: $STATUS)"
            exit 1
          fi

          # Check for regressions
          REGRESSIONS=$(curl -s https://api.regressionbot.com/job/$JOB_ID/summary \
            -H "x-api-key: $REGRESSIONBOT_API_KEY" | jq '.regressionCount // 0')
          if [ "$REGRESSIONS" -gt 0 ]; then
            echo "::error::$REGRESSIONS regression(s) detected"
            exit 1
          fi

Troubleshooting