API

Run audits and pull full reports from your own code. Everything is REST over HTTPS, request and response bodies are JSON, and authentication is a bearer token.

Available on the Pro and Agency plans. Create a key under Account → API keys.

Authentication

Send your key in the Authorization header. Keys are shown once at creation and stored only as a hash, so a lost key is replaced rather than recovered. Treat one like a password: it carries the full permissions of your account.

curl https://sitedocket.com/api/v1/pub/me \
  -H "Authorization: Bearer sdk_live_your_key_here"

Rate limits

60 requests per minute per key. Exceeding it returns 429 with a Retry-Afterheader giving the seconds to wait. Audits additionally consume your plan's monthly quota; once it is spent, requests return 402.

Endpoints

GET/api/v1/pub/me

Your account, plan and remaining monthly audit quota. Useful as a credential check.

{
  "email": "you@agency.com",
  "plan": "pro",
  "audits_used_this_month": 12,
  "audits_included": 30,
  "audits_remaining": 18
}

POST/api/v1/pub/audits

Queue an audit. Returns immediately with an id; a full run takes roughly 30 to 90 seconds. Poll the single-audit endpoint until status is done.

curl -X POST https://sitedocket.com/api/v1/pub/audits \
  -H "Authorization: Bearer sdk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

{ "id": 128, "status": "pending", "url": "https://example.com" }

Pass an optional modules array to run a subset, e.g. ["seo", "technical"]. Omit it to run everything.

GET/api/v1/pub/audits/{id}

One audit in full: every score, every finding with its severity, effort tier, impact and how-to-fix text, plus the raw per-category data behind the report panels.

{
  "id": 128,
  "url": "https://example.com",
  "status": "done",
  "overall_score": 79,
  "scores": { "seo": 98, "technical": 73, "performance": 67, "...": 0 },
  "issues": [
    {
      "category": "technical",
      "severity": "warning",
      "code": "missing_csp",
      "title": "No Content-Security-Policy header",
      "how_to_fix": "...",
      "effort": "moderate",
      "effort_label": "~1 hr fix"
    }
  ]
}

GET/api/v1/pub/audits

Your audits, newest first. Accepts ?limit= up to 200.

Errors

Every error is a JSON object with an error string. 401 means the key is missing, malformed or revoked; 403 means your plan does not include API access; 402 means the monthly quota is spent; 404 is returned for an audit that does not exist or is not yours.