Website audit API

Run SiteAssay website audits from your own code: authentication, endpoints, webhooks, limits and the OpenAPI specification.

The SiteAssay API runs the same website audit the app runs, from your own code. Start an audit with one request, then either poll for the result or have a webhook tell you when it is ready. It is a versioned JSON API, and the OpenAPI specification describes every endpoint and field.

API access is included on the Agency and Scale plans. See pricing for what each plan includes.

Authentication

Create a personal access token under Settings → API and send it as a bearer token on every request:

Authorization: Bearer <your token> Accept: application/json

A token belongs to the person who created it, and it sees only that agency's audits and reports. Remove somebody from the agency and their tokens stop working with them.

Endpoints

An id that belongs to another agency returns 404, the same as an id that does not exist.

Running an audit

An audit takes minutes rather than milliseconds, because it loads the site in a real browser and runs every check in the audit engine. So starting one does not wait for it:

curl -X POST https://siteassay.com/api/v1/audits \ -H "Authorization: Bearer <your token>" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com", "name": "Example Ltd"}'

The response is 202 Accepted with the audit's id and status: "queued". From there, either poll GET /api/v1/audits/{id} until the status is done or failed, or set up a webhook and stop polling.

The payload of a finished audit has a stable, versioned shape: a change inside the audit engine does not change what your integration parses. How the numbers in it are turned into scores is explained in scoring.

Webhooks

Add a webhook under Settings → API and SiteAssay posts JSON to it when something finishes.

{ "event_id": "evt_...", "event": "audit.completed", "api_version": "v1", "created_at": "2026-11-02T10:00:00+00:00", "data": { "...": "as the matching GET returns" } }

Every delivery carries an X-SiteAssay-Signature: sha256=<hmac> header: an HMAC-SHA256 of the raw request body, keyed with the signing secret shown once when you save the webhook. Verify it against the raw bytes, before parsing. Delivery is at least once, so use event_id to ignore repeats. A delivery is attempted three times and then dropped, so keep polling as a fallback for a receiver that may be down.

Errors and limits

Two limits apply. Requests are limited per agency per minute, and audits started are limited per hour, underneath your plan's monthly allowance. A refused request does not use up an audit. Nothing is billed after the fact: once the allowance and any packs you have bought are used, new audits return 422 until the next period. The usage page explains the allowances.

Using it from an AI assistant

The same audits and reports are available to AI assistants over the Model Context Protocol, at /mcp, with the same token. An assistant can start an audit, check on it and read the finished report, under the same limits and the same allowance as the API.

Questions

Which plans include the API?

Agency and Scale. The token, the limits and the allowance are the same whether you call the API directly or through an AI assistant.

Can I audit a site without adding it to my workspace first?

Yes. Send a url and a name and the audit runs on its own. Send the id of a business already in your workspace instead and the audit is attached to it.

Is there a sandbox?

Not a separate one. Every audit uses your allowance, so test against a small number of sites you know well.