Start an audit, read the score.
Four endpoints. Included with Pro and Team, and counted against the same allowance as audits you start on the site.
1. Send your key
Make a key in your settings. It is shown once. Send it with every request, and keep it on a server: a key in a web page can be read by anyone who opens it.
Check a key
curl https://uxsignal.io/api/v1/me \
-H "Authorization: Bearer $UXS_KEY"Answer
{
"email": "you@studio.com",
"plan": "team",
"siteAudits": { "used": 3, "allowance": 12, "credits": 0, "pagesPerAudit": 25 }
}2. Start an audit
Send the address. Scope is page for that one page, or site for its main pages. For a site you may name the pages yourself; they must be on the same domain.
One page
curl https://uxsignal.io/api/v1/audits \
-H "Authorization: Bearer $UXS_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://fernwell.co/pricing"}'A site, with the pages named
curl https://uxsignal.io/api/v1/audits \
-H "Authorization: Bearer $UXS_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "fernwell.co",
"scope": "site",
"pages": ["https://fernwell.co/", "https://fernwell.co/pricing"]
}'Answer, straight away
{
"audit": {
"id": "8b8fb3aa-f8b0-481d-b926-9adcc493cbb1",
"url": "https://fernwell.co/pricing",
"scope": "page",
"status": "pending",
"score": null,
"progress": { "percent": 8, "message": "Queued for worker" },
"reportUrl": "https://uxsignal.io/audits/8b8fb3aa-f8b0-481d-b926-9adcc493cbb1"
}
}3. Wait, then read it
A page takes two to three minutes; a site takes longer. Ask every fifteen seconds or so until the status is completed or failed.
Ask
curl https://uxsignal.io/api/v1/audits/8b8fb3aa-f8b0-481d-b926-9adcc493cbb1 \
-H "Authorization: Bearer $UXS_KEY"Answer, when it is done
{
"audit": {
"id": "8b8fb3aa-f8b0-481d-b926-9adcc493cbb1",
"url": "https://fernwell.co/",
"scope": "site",
"status": "completed",
"score": 70,
"summary": "The front door is fixed and the score moved. …",
"issueCount": 11,
"topIssues": [
{
"title": "Annual pricing toggle is easy to miss",
"severity": "high",
"category": "clarityMicrocopy",
"points": 5,
"fix": "Show the annual savings inline on the toggle."
}
],
"pages": [
{ "url": "https://fernwell.co/pricing", "label": "Pricing", "score": 64, "issueCount": 4 }
],
"progress": { "percent": 100, "message": "Report ready" },
"error": null,
"reportUrl": "https://uxsignal.io/audits/8b8fb3aa-f8b0-481d-b926-9adcc493cbb1",
"createdAt": "2026-10-07T18:20:20.000Z",
"completedAt": "2026-10-07T18:27:02.000Z"
}
}topIssues holds up to five, the costliest first. pages is filled for a site and null for a single page. The full report, with its evidence, is at reportUrl.
4. List recent audits
The newest twenty
curl "https://uxsignal.io/api/v1/audits?limit=20" \
-H "Authorization: Bearer $UXS_KEY"The answer is { "audits": [ … ] }, each in the shape above. The limit runs from 1 to 50.
When it says no
Every refusal has the same shape, with a code to act on and a sentence you can show a person.
{ "error": { "code": "quota_exceeded", "message": "…" } }| 401 | invalid_key | The key is missing, mistyped or revoked. |
| 403 | plan_required | The account is on the free plan. |
| 400 | url_required | No address was sent. |
| 400 | invalid_url | The address is not a website URL. |
| 400 | invalid_scope | Scope was neither page nor site. |
| 402 | quota_exceeded | The month's full-site audits are used. |
| 429 | daily_limit | 200 audits were started in 24 hours. |
| 404 | not_found | No audit with that id on this account. |