Sitejar API

Authentication

Generate an API key from your account (POST /v1/apikeys, using the JWT you get from logging in), then send it as a bearer token on every request: Authorization: Bearer sj_live_.... Keys are shown in full exactly once, at creation - Sitejar only ever stores a one-way hash afterward.

curl -X POST https://api.sitejar.app/v1/apikeys \
  -H "Authorization: Bearer <your JWT access token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI pipeline"}'

# {"id":"...", "name":"CI pipeline", "key":"sj_live_...", "createdAt":"..."}
# The "key" field is shown exactly once - store it as a secret now.

Endpoints

Starting a scan

curl -X POST https://api.sitejar.app/v1/public/scans \
  -H "Authorization: Bearer sj_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-site.com"}'

# {"scanId":"5f2b1e3a-..."}

Scans run asynchronously - poll the report endpoint until status is done (or failed).

Pass/fail gating

Add ?fail_below=<0-100>&dimension=<name|overall> to the report endpoint and the response gains a server-computed "pass" boolean - true when that dimension's score (or the mean of all six, for overall) is at or above the threshold. Both params are required together; dimension must be overall or one of accessibility, security, privacy, darkPattern, quality, seo. This computes the same pass/fail rule server-side so every caller applies it identically, instead of each CI script re-implementing its own score comparison.

curl https://api.sitejar.app/v1/public/scans/5f2b1e3a-.../report?fail_below=90&dimension=accessibility \
  -H "Authorization: Bearer sj_live_..."

# {"scanId":"5f2b1e3a-...", "status":"done", "scores":{...}, "pass": true}
# "pass" only appears when both params are given - it is omitted otherwise.

Exporting reports

Once a scan is done, the same report is available as Markdown (a task list you can paste into a GitHub issue or Notion page), CSV (for Sheets/Airtable), and JSON - swap the extension on the report path. Counts always agree across formats, and with the dashboard and PDF. Available on every paid plan; a free key gets 403 {"error":"export_requires_upgrade"}.

curl https://api.sitejar.app/v1/public/scans/5f2b1e3a-.../report.md \
  -H "Authorization: Bearer sj_live_..."

# A GitHub/Notion-ready Markdown task list (text/markdown; Content-Disposition names the file).
# Swap the extension for the other formats: report.csv (RFC 4180, UTF-8 BOM) or report.json
# ({schemaVersion, exportedAt, scanId, requestedHost, scores, findings}). Paid plans only -
# a free key gets 403 {"error":"export_requires_upgrade"}.

Rate limits

Fixed per-hour limits, keyed to your plan, and shared across every /v1/public/* call - polling the report endpoint spends quota the same way starting a scan does. Every response includes X-RateLimit-Limit/X-RateLimit-Remaining headers; going over returns 429 with a Retry-After header telling you how many seconds until the window resets.

Errors

Exact response bodies, taken straight from the API - nothing here is illustrative.

Gate your CI pipeline

The pattern most teams start with: scan a staging deploy on every pull request, and fail the build if the accessibility score drops below 90 - using the pass field from "Pass/fail gating" above so the workflow doesn't need to parse scores itself.

name: Compliance gate
on: [pull_request]

jobs:
  sitejar-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Run Sitejar compliance scan
        env:
          SITEJAR_API_KEY: ${{ secrets.SITEJAR_API_KEY }}
          TARGET_URL: https://staging.your-site.com
        run: |
          scan_id=$(curl -s -X POST https://api.sitejar.app/v1/public/scans \
            -H "Authorization: Bearer $SITEJAR_API_KEY" \
            -H "Content-Type: application/json" \
            -d "{\"url\": \"$TARGET_URL\"}" | jq -r '.scanId')

          echo "Scan $scan_id queued - polling for completion..."

          status=""
          for _ in $(seq 1 30); do
            report=$(curl -s "https://api.sitejar.app/v1/public/scans/$scan_id/report?fail_below=90&dimension=accessibility" \
              -H "Authorization: Bearer $SITEJAR_API_KEY")
            status=$(echo "$report" | jq -r '.status')
            [ "$status" = "done" ] && break
            [ "$status" = "failed" ] && { echo "::error::Scan failed"; exit 1; }
            sleep 10
          done

          # Without this check, a scan that's still "queued" or "running"
          # after all 30 polls falls through silently - "$report" is stale
          # and "pass" isn't present yet, so the step would pass the build
          # by accident instead of failing it.
          if [ "$status" != "done" ]; then
            echo "::error::Scan timed out after 5 minutes - it never reached status=done"
            exit 1
          fi

          pass=$(echo "$report" | jq -r '.pass')
          echo "Accessibility gate (fail_below=90): pass=$pass"

          if [ "$pass" != "true" ]; then
            echo "::error::Accessibility score is below the required 90 - failing the build."
            exit 1
          fi