The HTTP API

The public API

No authentication and no account. Described by an OpenAPI 3.1 specification the site serves about itself; a test holds that specification against the routes that exist on disk, so what it promises is what runs.

Read the OpenAPI specification

curl -X POST https://axrush.com/api/v1/scan \
  -H "content-type: application/json" \
  -d '{"domain":"example.com"}'

curl https://axrush.com/api/v1/report/example.com

curl https://axrush.com/api/v1/agent-tasks/example.com

Your sites, authenticated

The /api/v1/me endpoints cover your sites, reports, history, fixes, comparisons, verification records, Answers and private agent runs. Results include measurement dates, engine versions and page coverage. Reading stored Answers and agent runs never starts a model call or spends credits.

Every endpoint below takes an organization API key as a bearer token and is part of the paid plan. Create keys on your account page

Every request carries the key as a bearer token:

curl -H "authorization: Bearer axr_..." \
  https://axrush.com/api/v1/me/sites

• GET /api/v1/me/sites: your sites with their latest and previous scores; add limit or offset to paginate
• GET /api/v1/me/sites/{id}/report: the latest full report for one site, pages included
• GET /api/v1/me/sites/{id}/history: finished scans, newest first, with engine versions and nextOffset; returns 100 by default for existing integrations
• POST /api/v1/me/sites/{id}/scan: queues a scan of your own site and returns its id at once
• GET /api/v1/me/scans/{id}: polls one scan until it settles; queued and running include pollAfterSeconds, succeeded carries the full report
• GET /api/v1/me/sites/{id}/fixes: the open work on one site, ordered by the points each fix returns
• GET /api/v1/me/sites/{id}/fixes/{checkId}: every finding behind one check, its guide, and the whole fix as one prose block
• GET /api/v1/me/sites/{id}/artifacts/{kind}: the bytes of a generated file, with the path and headers to serve it at
• GET /api/v1/me/sites/{id}/compare: compares the latest two finished scans, or the pair selected with before_scan_id and after_scan_id; includes resolved findings, regressions and engine or coverage warnings
• GET /api/v1/me/sites/{id}/verifications: existing verification records, including pending, measuring, verified and expired outcomes; never schedules verification
• GET /api/v1/me/sites/{id}/answers: stored Answers passes and their answers, citations, mentions and ranking; select pass_id or read the latest finished pass
• GET /api/v1/me/sites/{id}/agent-runs: private agent runs, including unpublished runs, with verdicts and evidence; select run_id or paginate

Read every page

Pass limit (1–50, default 20) and offset (0–10000, default 0). Continue with nextOffset as the next offset, keeping the same limit, until it is null. On /me/sites, omit both parameters to keep the existing unpaged response. On /history, omit both to keep the existing 100-scan default. New lists default to 20. pass_id selects an Answers pass independently of the listed page; run_id selects one agent run and ignores pagination.

curl --fail-with-body -H "authorization: Bearer $AXRUSH_API_KEY" \
  "https://axrush.com/api/v1/me/sites/$SITE_ID/history?limit=20&offset=0"

Verify what changed

Omit both scan ids to compare the latest two finished scans, or supply both in chronological order. Read comparable and warnings before interpreting scoreDelta: changes in engine version, measured pages or applicability can prevent a fair comparison. Check differences describe the origin only. Answers, verification records and agent runs are read-only through these endpoints.

curl --fail-with-body -H "authorization: Bearer $AXRUSH_API_KEY" \
  "https://axrush.com/api/v1/me/sites/$SITE_ID/compare?before_scan_id=$BEFORE_SCAN_ID&after_scan_id=$AFTER_SCAN_ID"

Reports expose scope, checksScope, pageCount and informational checks. discoveredUrls counts discovery, not measured pages. For compatibility, v1 retains numeric scores for N/A checks: always inspect applicable before treating a score as a failure. Existing field names, including score, scannedAt and history finishedAt, are unchanged.

A CI gate that says what to fix

Trigger a scan after a deploy, poll until it settles, and fail the build when the score falls below your bar. A failing gate prints the work list, so the log says what to fix rather than only that something is wrong:

set -eu
SCAN=$(curl --fail-with-body -sS -X POST -H "authorization: Bearer $AXRUSH_API_KEY" \
  "https://axrush.com/api/v1/me/sites/$SITE_ID/scan" | jq -er .scanId)

for attempt in $(seq 1 60); do
  BODY=$(curl --fail-with-body -sS -H "authorization: Bearer $AXRUSH_API_KEY" \
    "https://axrush.com/api/v1/me/scans/$SCAN")
  STATUS=$(echo "$BODY" | jq -er .status)
  [ "$STATUS" = queued ] || [ "$STATUS" = running ] || break
  sleep 5
done

[ "$STATUS" = succeeded ] || { echo "Scan failed or timed out: $STATUS"; exit 1; }
SCORE=$(echo "$BODY" | jq -er .report.score)
[ "$SCORE" -ge 90 ] || {
  echo "score $SCORE fell below 90; what to fix first:"
  curl --fail-with-body -sS -H "authorization: Bearer $AXRUSH_API_KEY" \
    "https://axrush.com/api/v1/me/sites/$SITE_ID/fixes" \
    | jq -r '.fixes[] | select(.gain > 0) | "  +\(.gain)  \(.checkId)  \(.headline)"'
  exit 1
}

Run the private engine

POST /api/v1/engine/audit executes an audit on AX Rush servers. This is the endpoint used by ax-audit 6. Send an organization API key with an active paid subscription; every audit verifies access again.

curl --fail-with-body https://axrush.com/api/v1/engine/audit \
  -H "authorization: Bearer $AXRUSH_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com","profile":"auto"}'

Required: url. Optional: checks (1–26 check ids), profile (auto, api, mcp, agent, docs, commerce or all), timeout (100–10000 ms per request), and retries (0–2). The response is an AuditReport with overallScore, results and engine. It is not saved to your site history; use /api/v1/me/sites/SITE_ID/scan for a stored site scan.

Only public HTTP(S) URLs on ports 80 and 443 are accepted. Localhost and private networks are unavailable because execution is remote. Requests are limited to 8 KiB, 10 audits per organization per hour and 5 per target per hour, with target limits shared across scan surfaces. A 429 response includes Retry-After.

Handle errors

Check the HTTP status before reading a successful response. Errors contain error and message: 400 for invalid input, 401 for a missing or revoked key, 403 for insufficient access, 404 for unavailable owned data, 409 for an already active site scan, 429 for rate limits, and 503 when a read or remote execution is temporarily unavailable. Engine requests over 8 KiB return 413. Private responses are not cached.