Public API

Audits over HTTP

Everything the page above does goes through a public JSON API. Create an audit, poll it until it finishes, download the PDF, then update or delete it with the edit token you were given on creation.

Base URL https://steelabs.tech/api/v1

Open API documentation

Explore endpoint details, request examples and an interactive API client in our GitBook documentation.

Endpoints

Method	Path	Token	What it does
GET	/audits	None	List publicly listed audits. Query: q, status, device, sort (created_at \| score \| name), order, limit (1–100), offset.
POST	/audits	None	Create an audit (JSON, or multipart with an attachment). Returns 201 and the editToken, once.
GET	/audits/{id}	None	One audit, including the full findings once it is done.
PATCH	/audits/{id}	Bearer	Change any field. Changing url, device, maxPages, checkAccessibility or scheduledFor re-runs it.
DELETE	/audits/{id}	Bearer	Delete the audit, its PDF report and its attachment. Returns 204.
POST	/audits/{id}/run	Bearer	Queue a fresh run with the current settings. Returns 202.
GET	/audits/{id}/report	None	The PDF report, once the status is done.
GET	/audits/{id}/attachment	None	The uploaded attachment, if any.
GET	/openapi.json	None	OpenAPI 3.1 description of all of the above.

Fields and validation

Field	Type	Rule
url	string (URL)	Required on create. Public http(s) only; private, loopback and metadata hosts are refused.
name	string	2–80 characters. Defaults to the domain.
device	enum	desktop or mobile. Default desktop.
maxPages	integer	1–10. Default 3.
passThreshold	number	0–100 in steps of 0.5. Default 70.
checkAccessibility	boolean	Default true.
scheduledFor	date-time	ISO 8601 with offset, from now up to 7 days ahead. Default now.
notes	string	Up to 1,000 characters.
listed	boolean	Show in the public list (GET /audits). Default false: reachable only by id.
attachment	file	Multipart only. PNG, JPEG, WebP or PDF, 4 MB or less, checked by content.

Errors use one shape: { ok: false, error, message?, fields? }, with status 400, 401, 403, 404, 413, 415, 429 or 503. Writes are limited per network and site-wide per hour.

Examples

Create an audit

curl -s -X POST https://steelabs.tech/api/v1/audits \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com","device":"mobile","maxPages":2,"passThreshold":72.5,"checkAccessibility":true}'
# → 201 {"ok":true,"data":{"id":"…","status":"queued",…},"editToken":"…"}

With an attachment

curl -s -X POST https://steelabs.tech/api/v1/audits \
  -F url=example.com -F name='Landing page' -F attachment=@brief.pdf

Poll until done, then fetch the report

curl -s https://steelabs.tech/api/v1/audits/$ID | jq '.data.status, .data.score'
curl -s -o report.pdf https://steelabs.tech/api/v1/audits/$ID/report

Update and delete with the edit token

curl -s -X PATCH https://steelabs.tech/api/v1/audits/$ID \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"name":"Renamed","passThreshold":80}'

curl -s -X DELETE https://steelabs.tech/api/v1/audits/$ID -H "authorization: Bearer $TOKEN"   # → 204

Validation errors name the field

curl -s -X POST https://steelabs.tech/api/v1/audits -H 'content-type: application/json' \
  -d '{"url":"http://127.0.0.1","maxPages":40,"passThreshold":"high"}'
# → 400 {"ok":false,"error":"validation","fields":{
#     "url":"That address points to a private or local network.",
#     "maxPages":"Crawl at most 10 pages.",
#     "passThreshold":"Enter a number."}}

openapi.json