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.

Capture Options

Sticky and fixed elements are handled automatically on every full-page capture — there is no flag to toggle. For content that needs custom treatment, customCss can be set at project creation or updated later, and applies to server-side (cloud worker) capture.

Scheduled Checks

A project can run on its own, with nobody triggering it. This is what catches the changes no deploy caused — a third-party script updating itself, an edit made in your CMS, a web font that stopped loading, a certificate that expired. Your CI never sees any of those, because none of them came from a commit.

Why a schedule requires a rolling baseline

Setting schedule on a managed project without baselinePolicy: "rolling" is rejected by the API — live-vs-live projects store no baseline, so the policy does not apply to them and neither does the requirement. The reason is worth understanding rather than working around: on the default policy the baseline only moves when a person approves a run. So a change that is reported and not approved is still a difference from the baseline tomorrow — and the day after. A daily check would email you the same change every morning until you acted on it, which is how people learn to ignore alerts.

Rolling advances the baseline on every run, so each check compares against yesterday and reports only what is genuinely new. It advances even when a run finds something wrong — otherwise you are back to the repeat-alert problem. The evidence is not lost: the run keeps its before and after images for 14 days, and the alert links to them.

Turning a schedule off

Send {"schedule": null}. Omitting the field does nothing — a project update is a patch, so leaving schedule out of the body leaves the existing schedule running. Setting or clearing a schedule is metadata: it does not touch your baselines, so you can turn a check on to try it and off again without re-priming the project.

When a scheduled run happens

schedule sets how often, not what time. A sweep runs every hour and starts every project that has come due, and the interval is measured from the moment the last scheduled run started. So turning on a daily schedule at 09:20 gets its first run at the next sweep — some time before 10:20 — and every check after that anchors to whenever that first one began. A run may start up to 30 minutes early, which is the tolerance that stops a daily check drifting later by a few minutes every day.

There is no time-of-day or day-of-week setting yet. If you need a check at a specific hour, set the schedule at that hour, or trigger the run yourself from cron or a CI schedule and leave schedule unset.

A run that never starts — a lapsed plan, an exhausted monthly allowance — does not consume its slot: the project stays due and the next sweep tries again rather than silently losing a day. That is a different thing from a run that starts and cannot finish, which is covered under Alerts below. An unreachable site is the second kind: the run starts, every page fails to capture, and the check reports that it could not check anything.

Which key a scheduled run is billed to

Nobody is holding an API key when an unattended run starts, so the key that set the schedule is recorded with it and every scheduled run is attributed to that key. Set your schedule with an API key, not from a browser session: a run with no key recorded against it cannot meter AI usage, so its summaries are skipped and the alert email lists the changed pages without saying what changed on them. GET /project/{name} returns scheduleKeyId — if it is absent, set the schedule again using an API key.

Deleting that key does not stop the schedule — checks carry on running, and their usage shows against the deleted key's id rather than its name. To re-attribute a schedule to a different key, set schedule again using that key; that is a metadata change, so it leaves your baselines alone.

Alerts

When a scheduled run finds changes, your organisation's owners get an email describing what changed in plain English, with a link to the comparison. Runs you trigger yourself do not send email — the results are already in front of you.

A scheduled run that could not check your site also emails, and this is the one that matters most: nobody is watching an unattended check, so a check that stopped working would otherwise look exactly like a site with nothing wrong. Three shapes, all covered — a run that stopped outright (the sitemap would not load), a run that finished having failed to capture a single page (the site was down, or its credentials expired), and a run that never started at all (a lapsed plan, an exhausted allowance). Each names what stopped it and confirms the schedule is untouched. The first two are sent once per run; the third is sent at most once a day per project, because a lapsed plan stays lapsed and would otherwise mail you hourly.

A run where some pages failed and others succeeded is a real comparison, not a failure: it reports normally, and the failed pages appear as errors in the results. A clean run stays silent — there is no "all is well" email.

curl -X PUT https://api.regressionbot.com/project/marketing-site \
  -H "Authorization: Bearer $REGRESSIONBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "daily",
    "baselinePolicy": "rolling"
  }'

Gated Environments

Preview and staging environments are usually behind a door. testAuth and baseAuth carry the credential that opens it, so the crawler can reach the site at all — including the sitemap, which is otherwise the first thing to get a 401.

curl -X PUT https://api.regressionbot.com/project/staging-site \
  -H "Authorization: Bearer $REGRESSIONBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "testAuth": {
      "basic": { "username": "preview", "password": "..." }
    }
  }'

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.

Sitemap Crawling & Discovery

Instead of manually specifying every single page path to test, you can configure RegressionBot to discover pages dynamically by crawling your environment's sitemap.

How to Configure

Projects can be configured and run across all interfaces. Use the selectors below to choose your environment:

import { RegressionBot } from '@regressionbot/sdk';

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'])
  .check('/invoice')
  .check('/settings')
  .run();

import { RegressionBot } from '@regressionbot/sdk';

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

// Triggers a run against the saved project configuration
const job = await client.runProject('my-billing-app');

Troubleshooting