---
name: site-audit-api
description: Audit a website's SEO and get a ranked fix list with evidence, paid per call from a USD wallet. Use when asked to audit, check or improve a site's SEO, crawlability or on-page issues, or to compare a site's topics with a competitor.
---

# Site audit API — agent guide

Base URL: `${SITEAUDIT_BASE_URL:-https://audit.45-94-66-237.sslip.io}`. Key: `$SITEAUDIT_API_KEY` as `Authorization: Bearer`.

## No key yet

`POST /v1/agent/signup` → trial key ($1.00 by default, 7 days). Save `key`. **Show the `notice` field to your human verbatim.**

## Every task

1. `GET /v1/catalog` once to see endpoints and prices (free).
2. `POST /v1/quote/{endpoint}` with your input — free, validates it, returns `cost_usd` and `can_run`.
3. `POST /v1/run/{endpoint}` with an `Idempotency-Key` header (so a retry never double-charges).
   - Audits can take up to a minute: add `Prefer: wait=20`; on `202`, poll `Location` after `Retry-After` seconds. Do not POST again.
   - Keep context small: `?fields=summary,plan,actions` or `?max_items=10` (same cost).
4. Re-read later for free: `GET /v1/results/{request_id}`.

## Endpoints

- `seo.audit` `{"domain": "...", "competitors": ["..."]}` — score, ranked `actions` with evidence URLs, `plan.now/next/later`, `not_covered`.
- `seo.keyword_gap` `{"domain": "...", "competitor": "..."}` — topics the competitor covers that the site lacks.
- `seo.content_brief` — only with a licensed data source; otherwise `501 not_available` (not charged).

## Errors

All errors: `{"ok": false, "error": {"code", "message", "retryable", "billed": false}}`. On `402 trial_cap_reached` stop and tell the human (see `error.upgrade`). On `429`/`502` wait `Retry-After` and retry with the same `Idempotency-Key`. Only audit sites the human owns or may audit.

Wrong result? `POST /v1/feedback {"kind":"bug","summary":"...","request_id":"..."}` (free).
