From an empty account to a regression report.

Overview

The SBS public API is a read-mostly JSON API over HTTPS. It exposes the sites, runs, run results and queue jobs of exactly one organization: the one the API key belongs to. A key can never reach another organization's data.

Base URL https://sbspx.com/wp-json/sbs/public/v1

The version is part of the path (/sbs/public/v1). Breaking changes ship as a new version; additive fields may appear inside v1 without notice, so parse defensively and ignore keys you do not recognise.

Authentication

Every request carries a bearer key. Cookies and WordPress nonces are not accepted on this namespace — the API is for machines.

Authorization: Bearer sbs_live_YOUR_KEY_HERE

Keys look like sbs_live_… in production and sbs_test_… everywhere else, followed by 32 random characters. Only a SHA-256 hash of the key is stored, so the plaintext is shown exactly once, at creation, and can never be recovered.

Treat a key like a password: put it in an environment variable, never in a git repository or a browser.

Scopes

Each key carries an explicit list of scopes. A route refuses a key that lacks its scope, with sbs_forbidden.

Plan availability

API access is a plan feature. Read access and write access are gated separately, and the hourly rate limit is per plan.

Rate limits

Limits are counted per key in a fixed one-hour window. Every response — success or failure — carries the current state:

Refused requests still count against the window, so back off on 429 rather than retrying immediately.

Pagination

List routes accept page (1-based, default 1) and per_page (1–100, default 25). They return the totals both in the body (page, perPage, total, totalPages) and in the X-Total-Count / X-Total-Pages headers.

Errors

Errors are always JSON with a stable machine-readable code:

{
  "code": "sbs_rate_limited",
  "message": "Rate limit exceeded: 600 requests per hour. Retry in 812 seconds.",
  "data": { "status": 429, "retryAfter": 812 }
}

Branch on code, never on the message text.

Two things the table does not say on its own

Subscription state arrives as sbs_plan_limit. There is no separate sbs_trial_expired or sbs_subscription_required code on this namespace. An expired trial or a canceled subscription drops the organization back to the free tier's entitlements, which do not include API access, so the refusal comes back as 403 sbs_plan_limit like any other missing capability. Read data.reason to tell the cases apart — it is one of plan_feature_unavailable, org_suspended or org_not_found — and data.upgradeUrl where an upgrade would fix it.

The organization's “disable AI analysis” switch does not change any response here. No route in this API requests an AI analysis: POST /sites/{identifier}/runs accepts only baseline, comparison and console. When the switch is off, an API-triggered comparison is still accepted and still runs; what is refused is the automatic analysis that would otherwise follow it, inside the platform, before any image is sent — so the run's results simply come back without an analysis. That refusal is what clause 11 of the Data Processing Agreement means when it says the platform refuses the analysis for a run started through the public API: the analysis is refused, not the run. The platform reserves the code sbs_ai_disabled (403, reason org_ai_disabled) for an AI analysis that is requested directly and refused by that switch. No route in this namespace returns it today, and it will be added to the table above on the day one does. It is documented here so that an integrator branching on code knows the name exists and what it would mean, rather than meeting it undocumented.

Quick start

Verify a key and see which organization it is bound to:

export SBS_KEY=sbs_live_YOUR_KEY_HERE
curl -sS -H "Authorization: Bearer $SBS_KEY" \
  https://sbspx.com/wp-json/sbs/public/v1/ping

List your sites, then trigger a comparison on one of them (write scope + Agency plan or above):

curl -sS -H "Authorization: Bearer $SBS_KEY" \
  "https://sbspx.com/wp-json/sbs/public/v1/sites?per_page=10"

curl -sS -X POST \
  -H "Authorization: Bearer $SBS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"comparison","environment":"production"}' \
  https://sbspx.com/wp-json/sbs/public/v1/sites/SITE_ID/runs

Then poll the job until it leaves pending/running:

curl -sS -H "Authorization: Bearer $SBS_KEY" \
  https://sbspx.com/wp-json/sbs/public/v1/jobs/JOB_ID

Endpoints

This list is generated from the registered routes, so it always matches what the server serves.

curl -sS -H "Authorization: Bearer $SBS_KEY" \
  https://sbspx.com/wp-json/sbs/public/v1/ping

{ "ok": true, "version": "1.0.0", "mode": "test", "org": { "id": 9, "slug": "acme", "name": "Acme" }, "scopes": ["sites:read"] }

curl -sS -H "Authorization: Bearer $SBS_KEY" \
  https://sbspx.com/wp-json/sbs/public/v1/sites

{ "sites": [ { "id": "…", "slug": "acme-com", "name": "Acme", "enabled": true, … } ], "page": 1, "perPage": 25, "total": 4, "totalPages": 1 }

curl -sS -H "Authorization: Bearer $SBS_KEY" \
  https://sbspx.com/wp-json/sbs/public/v1/sites/SITE_ID

{ "id": "…", "slug": "acme-com", "environments": [...], "viewports": [...], "urlCount": 12 }

curl -sS -H "Authorization: Bearer $SBS_KEY" \
  https://sbspx.com/wp-json/sbs/public/v1/sites/SITE_ID/runs

{ "runs": [ { "runId": "20260811-091500", "type": "comparison", "summary": {...} } ], "total": 31 }

curl -sS -X POST \
  -H "Authorization: Bearer $SBS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"comparison","environment":"production"}' \
  https://sbspx.com/wp-json/sbs/public/v1/sites/SITE_ID/runs

{ "jobId": "job-20260811-091500-ab12", "status": "pending", "action": "comparison", "environment": "production" }

curl -sS -H "Authorization: Bearer $SBS_KEY" \
  https://sbspx.com/wp-json/sbs/public/v1/runs/RUN_ID

{ "runId": "20260811-091500", "site": "acme-com", "type": "comparison", "summary": {...} }

curl -sS -H "Authorization: Bearer $SBS_KEY" \
  https://sbspx.com/wp-json/sbs/public/v1/runs/RUN_ID/results

{ "runId": "…", "results": [ { "path": "/", "viewport": "desktop", "status": "diff", "diffPercentage": 1.4 } ], "total": 24 }

curl -sS -H "Authorization: Bearer $SBS_KEY" \
  https://sbspx.com/wp-json/sbs/public/v1/jobs/JOB_ID

{ "jobId": "job-…", "status": "completed", "runId": "20260811-091500", "error": null }

curl -sS -H "Authorization: Bearer $SBS_KEY" \
  https://sbspx.com/wp-json/sbs/public/v1/jobs

{ "jobs": [ { "jobId": "job-…", "action": "comparison", "status": "pending" } ], "total": 3 }

curl -sS -H "Authorization: Bearer $SBS_KEY" \
  https://sbspx.com/wp-json/sbs/public/v1/usage

{ "plan": { "slug": "plan-agency", "name": "Agency" }, "limits": {...}, "period": {...} }

Notes and guarantees

• Tenancy. Site, run and job identifiers are resolved inside the key's organization. An identifier belonging to another organization returns 404, so the API never reveals that it exists.
• Site identifiers. {identifier} accepts the site's stable storage id, its numeric id, or its slug. Prefer the storage id returned as id — slugs can be renamed.
• Triggering runs is asynchronous. POST /sites/{identifier}/runs returns 202 with a jobId; the run appears once a queue worker has processed it.
• Limits of 0 mean unlimited everywhere in this API, including X-RateLimit-Limit.
• Usage. Every authenticated request is metered as one api_request against the organization and is visible on the usage screen.