API reference

Trigger checks from CI, get a pass/fail result, and be notified when it’s done.

Authentication

Every request is scoped to a space. Authenticate with a space API key as a bearer token, or with a logged-in dashboard session.

Create a key under Settings → Developers, then send it as:

Authorization: Bearer <your-api-key>

Start a run

A run executes every enabled check for a site against an input — an uploaded build ZIP, a list of live URLs, or both.

POST /api/v1/sites/:siteId/runs

Send multipart/form-data with any of these fields:

Field	Type	Notes
`archive`	file (.zip)	Your build output, zipped (the folder with the generated HTML). Up to 200 MB.
`urls`	string	JSON array or newline/comma-separated list of live URLs to run against. Provide this instead of — or alongside — a ZIP.
`suite`	string	Optional. Which checks to run: a suite id, `all`, or `ungrouped`. Defaults to the site's active suite, else ungrouped.
`label`	string	Optional. A commit SHA or release name to identify the run.
`webhookUrl`	string	Optional. We POST the run summary here when it finishes. Must be a public http(s) URL.
`webhookToken`	string	Optional. Echoed as `Authorization: Bearer <token>` on the webhook POST so you can verify it.

You must send an archive, a urls list, or both.

Example — a build ZIP from CI

curl -X POST https://app.sitetools.pro/api/v1/sites/$SITE_ID/runs \
  -H "Authorization: Bearer $SITETOOLS_KEY" \
  -F [email protected] \
  -F label=$GITHUB_SHA

Example — live URLs + a webhook

curl -X POST https://app.sitetools.pro/api/v1/sites/$SITE_ID/runs \
  -H "Authorization: Bearer $SITETOOLS_KEY" \
  -F 'urls=https://example.com/
https://example.com/pricing' \
  -F webhookUrl=https://ci.example.com/hooks/sitetools \
  -F webhookToken=$HOOK_SECRET

Response

The run is queued immediately and processed in the background. You get back the run, including its id and status.

{
  "doc": {
    "_id": "6a55…c7cd",
    "status": "queued",
    "source": "api",
    "deep": true,
    "browser": false,
    "notice": "This run includes deep checks and may take a while…"
  }
}

deep / browser tell you whether the run includes slower tiers (whole-site checks, or ones that render pages in a real browser) — those take longer, so poll or use a webhook.

Check on a run

GET /api/v1/sites/:siteId/runs/:runId

Returns the run plus every check result with its findings. Status moves queued → running → completed (or failed).

{
  "doc": {
    "run": {
      "status": "completed",
      "durationMs": 812,
      "summary": { "checks": 12, "passed": 9, "failed": 2, "warnings": 1, "pages": 1, "score": 75 },
      "logs": [ { "seq": 1, "level": "info", "message": "Run started." }, … ]
    },
    "results": [
      { "name": "Broken internal links", "status": "passed", "findingCount": 0, "durationMs": 3 },
      { "name": "Social share image", "status": "failed", "findingCount": 1, "findings": [ … ] }
    ]
  }
}

Fail your CI step when summary.failed > 0.

Webhooks

If you pass a webhookUrl, we POST JSON to it once the run ends — no polling needed:

{
  "runId": "6a55…c7cd",
  "siteId": "6a54…cd08",
  "status": "completed",
  "label": "v2.4.0",
  "summary": { "passed": 9, "failed": 2, "warnings": 1, "score": 75 },
  "durationMs": 812
}

Delivery is best-effort with a 10-second timeout. For security we re-resolve the host at delivery time and never follow redirects, so a webhook can’t be bounced to an internal address.

Scheduled runs

You can also run a suite automatically on a set interval — nightly, weekly, or on your own cron — from a site → Schedules. Because there's no build to upload unattended, scheduled runs check live URLs: the site's known pages (from its resource inventory) plus any URLs you add, minus ones you exclude.

Each schedule has its own notification settings — email, a webhook, or an in-app record — and you choose when it alerts you: on failure, only on new issues, on every run, or when a run errors. Use Run now to fire one immediately without waiting for the next tick.

Check tiers & timing

Build checks — parse your HTML/CSS. Milliseconds.
Deep checks — whole-site (duplicate titles, broken links) or a live header fetch. Seconds.
Browser checks — render each page in headless Chromium (mobile + desktop): Core Web Vitals, console errors, accessibility, visual regression. Tens of seconds; capped at 25 pages per run.
AI checks — an LLM judges your content (a custom rule, copy quality, semantic SEO, cross-page consistency). Runs via the AI Gateway and consumes credits based on real usage; a run is rejected if the space has no credits.

A run is routed to the heaviest tier’s worker (browser > AI > build), which also runs the lighter tiers. Everything finishes asynchronously — use the run id or a webhook. A run’s response includes deep, browser, and ai flags.

Limits

Build ZIP: up to 200 MB, 5,000 pages.
Browser runs: up to 25 pages visited per run.
URLs must be public http(s) addresses (private/loopback hosts are rejected).

← All docs Guide: Run checks in CI →