API Documentation

Run website audits, monitor AI visibility, and pull prioritized fixes programmatically. Call the REST API directly, or let Claude and other AI assistants call it for you through the Website Auditor MCP server. Built for IT departments at small-to-medium businesses and solo entrepreneurs.

Use It From Your AI Assistant (MCP)

Every capability below is also exposed through the official Website Auditor MCP server. Connect it to Claude Desktop, Claude Code, or any MCP-capable client and your assistant can run audits, track what changed, benchmark against peers, and generate fixes conversationally.

The MCP server is a thin client over this REST API: it authenticates with the same wa_ API key you create in the admin portal, and enforcement happens server-side. Anything the MCP can do, you can also do directly with curl — same endpoints, same entitlements.

MCP Tools → REST Endpoints

MCP Tool	Backed By
get_ai_visibility, run_audit	`GET /api/audit`
compare_competitors	`GET /api/audit` (one audit per competitor)
get_changes	`GET /api/ai-visibility-history`
track_site / untrack_site	`POST` / `DELETE /api/tracked-domains`
list_tracked_sites	`GET /api/tracked-domains`
get_monitoring_status	`GET /api/monitoring-status`
get_benchmark	`GET /api/benchmark`
get_recommendations	`GET /api/recommendations`
generate_schema	`GET /api/schema`
get_report	`GET /api/report`

Auditing tools work with any valid API key. Monitoring, history, benchmarks, recommendations, schema, and report tools require a Website Auditor Pro subscription — exactly like the Pro endpoints they call.

Authentication

All API requests require an API key in the X-API-Key header. Keys start with wa_.

Getting Your API Key

Visit /admin_portal and sign in with Google
Create a new API key — the plaintext key is shown once, copy it immediately
Send the key in the X-API-Key header on every request
Revoke or rotate keys any time from the portal

Example Request

curl "https://api.website-auditor.io/api/audit?businessUrl=example.com&businessName=Example+Inc&businessCity=Seattle" \
  -H "X-API-Key: wa_your_api_key_here"

Rate Limits

5 audits per API key per day. The daily limit applies to /api/audit only — the read endpoints (subscription, history, benchmark, recommendations, schema, report, monitoring) don't consume it, and scheduled weekly re-audits of tracked domains run on a separate server-side budget. Rate limit headers are included in /api/audit responses:

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 3
X-RateLimit-Reset: 2026-03-31T23:59:59.999Z

Endpoints

Click an endpoint to expand it. Endpoints marked Pro require an active Website Auditor Pro subscription — free keys receive a 403. Everything else works with any valid API key.

GET

/api/audit

Trigger a website audit and return the results

⌄

Request

Headers:

X-API-Key: wa_your_api_key_here

Query Parameters:

Parameter	Type	Description
businessUrl	string	Website URL to audit required e.g. `example.com` or `https://example.com`
businessName	string	Name of the business required e.g. `Example Inc`
businessCity	string	City for local search analysis required e.g. `Seattle, WA`

Example URL:

GET /api/audit?businessUrl=example.com&businessName=Example+Inc&businessCity=Seattle

Responses

200 OK — Audit completed:

{
  "success": true,
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2026-03-31T12:00:00.000Z",
  "duration_ms": 15230,
  "audit": {
    "format": "html_report",
    "report_url": "https://website-auditor.io/report/abc123",
    "status": "completed",
    "note": "The audit completed successfully. The full HTML report is available at the report_url."
  }
}

400 Validation Error:

{
  "success": false,
  "error": "Validation failed",
  "details": [
    "businessUrl is required. Provide the website URL to audit.",
    "businessCity is required. Provide the city for local search analysis."
  ]
}

401 Invalid API Key:

{
  "success": false,
  "error": "Invalid API key. Check that your key is correct."
}

429 Rate Limited:

{
  "success": false,
  "error": "Rate limit exceeded. You can make 5 requests per day.",
  "rate_limit": {
    "limit": 5,
    "remaining": 0,
    "resets_at": "2026-03-31T23:59:59.999Z"
  }
}

502 Upstream Error:

{
  "success": false,
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": "The audit service returned an error. Please try again later.",
  "upstream_status": 500
}

GET

/api/subscription

Check the subscription tier behind your API key

⌄

Request

Headers:

X-API-Key: wa_your_api_key_here

No parameters. Works with any valid key — free or Pro — and only ever returns the key owner's own subscription.

Responses

200 OK:

{
  "success": true,
  "tier": "pro",
  "status": "active",
  "current_period_end": "2026-12-31T00:00:00.000Z",
  "cancel_at_period_end": false
}

tier is pro for active or trialing subscriptions, otherwise free. A user with no subscription returns status: "none".

GET

/api/ai-visibility-history Pro

Per-engine AI-visibility history for a domain, for computing deltas over time

⌄

Request

Headers:

X-API-Key: wa_your_api_key_here

Query Parameters:

Parameter	Type	Description
domain	string	Domain (or URL) whose history to return required
since	string	ISO-8601 timestamp; only snapshots at/after it are returned optional
limit	integer	Max snapshots, 1–100 optional

Snapshots accrue automatically — one per completed /api/audit run and one per scheduled weekly re-audit of a tracked domain.

Responses

200 OK:

{
  "success": true,
  "domain": "example.com",
  "count": 2,
  "insufficient_history": false,
  "snapshots": [
    {
      "captured_at": "2026-06-01T00:00:00.000Z",
      "run_id": "run-1",
      "score": 50,
      "by_engine": {
        "chatgpt": 40,
        "perplexity": 60,
        "claude": 55,
        "gemini": 45
      },
      "is_simulated": false
    }
  ]
}

With fewer than two snapshots the response sets insufficient_history: true and includes a message instead of a fabricated delta.

GET

/api/benchmark Pro

Benchmark a domain's AI visibility against all other audited sites

⌄

Request

Headers:

X-API-Key: wa_your_api_key_here

Query Parameters:

Parameter	Type	Description
domain	string	Domain (or URL) to benchmark required

Responses

200 OK:

{
  "success": true,
  "percentile": 65,
  "peer_median": 58,
  "sample_size": 41,
  "position_summary": "example.com scores 74 in AI visibility, ranking in the 65th percentile of 41 audited peer sites (peer median 58)."
}

percentile is null until the domain has an audit on record. The peer set is the latest real (non-simulated) score of every other audited domain.

GET

/api/recommendations Pro

Ranked, prioritized fixes from the domain's latest audit

⌄

Request

Headers:

X-API-Key: wa_your_api_key_here

Query Parameters:

Parameter	Type	Description
domain	string	Domain (or URL) to get fixes for required

Responses

200 OK:

{
  "success": true,
  "recommendations": [
    {
      "action": "Improve ChatGPT AI visibility",
      "why": "Your ChatGPT AI-visibility score is 38/100 — ChatGPT struggles to surface this site. Add clear headings, concise summaries, and Organization/FAQ schema so ChatGPT can extract and cite your content.",
      "expected_impact": "high",
      "effort": "medium"
    }
  ]
}

404 Not Found — no audit on record:

{
  "success": false,
  "error": "No audit on record for example.com. Run an audit first, then request recommendations."
}

GET

/api/schema Pro

Generate ready-to-paste JSON-LD structured data for a domain

⌄

Request

Headers:

X-API-Key: wa_your_api_key_here

Query Parameters:

Parameter	Type	Description
domain	string	Domain (or URL) to generate schema for required
type	string	One of `Organization`, `LocalBusiness`, `Product`, `FAQPage`, `auto` (default: auto) optional

Responses

200 OK:

{
  "success": true,
  "jsonld": {
    "@context": "https://schema.org",
    "@type": "Organization",
    "name": "Example",
    "url": "https://example.com",
    "logo": "https://example.com/logo.png",
    "sameAs": []
  },
  "placement_notes": "Add your real logo URL and social profile URLs (sameAs), then embed this in a <script type="application/ld+json"> tag in the <head> of every page."
}

GET

/api/report Pro

Shareable report URL and embeddable badge for the latest audit

⌄

Request

Headers:

X-API-Key: wa_your_api_key_here

Query Parameters:

Parameter	Type	Description
domain	string	Domain (or URL) whose latest report to share required

Responses

200 OK:

{
  "success": true,
  "report_url": "https://website-auditor.io/report/abc123",
  "badge_html": "<a href="https://website-auditor.io/report/abc123" ...>✓ Audited by Website Auditor</a>"
}

Returns 404 if the domain has no completed audit on record yet.

GET

/api/tracked-domains Pro

List the domains enrolled in weekly AI-visibility monitoring

⌄

Request

Headers:

X-API-Key: wa_your_api_key_here

No parameters. Returns only your own tracked domains, plus slot accounting against the 5-domain cap.

Responses

200 OK:

{
  "success": true,
  "limit": 5,
  "used": 2,
  "remaining": 3,
  "tracked": [
    {
      "domain": "example.com",
      "cadence": "weekly",
      "active": true,
      "digest_enabled": true,
      "last_audited_at": "2026-06-22T08:00:00.000Z",
      "next_run_at": "2026-06-29T08:00:00.000Z",
      "created_at": "2026-05-04T15:21:09.000Z"
    }
  ]
}

POST

/api/tracked-domains Pro

Enroll a domain for weekly monitoring (up to 5 domains)

⌄

Request

Headers:

X-API-Key: wa_your_api_key_here
Content-Type: application/json

Body:

{
  "domain": "example.com",
  "cadence": "weekly"
}

cadence is optional; weekly is the only supported value. Enrollment is idempotent — re-enrolling an already-tracked domain returns 200 with already_tracked: true.

Scheduled weekly re-audits run server-side and do not count against your 5-audits-per-day limit.

Responses

201 Created:

{
  "success": true,
  "created": true,
  "already_tracked": false,
  "tracked": {
    "domain": "example.com",
    "cadence": "weekly",
    "active": true,
    "digest_enabled": true,
    "last_audited_at": null,
    "next_run_at": "2026-07-09T08:00:00.000Z",
    "created_at": "2026-07-02T08:00:00.000Z"
  }
}

409 Conflict — cap reached:

{
  "success": false,
  "code": "LIMIT_REACHED",
  "error": "You can track up to 5 domains. Untrack one before adding another."
}

DELETE

/api/tracked-domains Pro

Stop monitoring a domain (frees one of your 5 slots)

⌄

Request

Headers:

X-API-Key: wa_your_api_key_here
Content-Type: application/json

Body (or send ?domain= as a query param):

{
  "domain": "example.com"
}

Idempotent: stopping a domain that isn't tracked succeeds with removed: false rather than erroring.

Responses

200 OK:

{
  "success": true,
  "removed": true,
  "limit": 5,
  "used": 1,
  "remaining": 4
}

GET

/api/monitoring-status Pro

Glanceable monitoring summary: latest score, last change, next run per tracked domain

⌄

Request

Headers:

X-API-Key: wa_your_api_key_here

No parameters. For each tracked domain, returns the latest and previous AI-visibility snapshots so you can show the current score and the most recent change.

Responses

200 OK:

{
  "success": true,
  "limit": 5,
  "used": 1,
  "remaining": 4,
  "sites": [
    {
      "domain": "example.com",
      "cadence": "weekly",
      "active": true,
      "last_audited_at": "2026-06-29T08:00:00.000Z",
      "next_run_at": "2026-07-06T08:00:00.000Z",
      "snapshots_count": 6,
      "latest": {
        "score": 62,
        "by_engine": {
          "chatgpt": 55,
          "perplexity": 70,
          "claude": 64,
          "gemini": 59
        },
        "captured_at": "2026-06-29T08:00:00.000Z",
        "is_simulated": false
      },
      "previous": {
        "score": 55,
        "by_engine": {
          "chatgpt": 45,
          "perplexity": 66,
          "claude": 58,
          "gemini": 51
        },
        "captured_at": "2026-06-22T08:00:00.000Z",
        "is_simulated": false
      }
    }
  ]
}

GET

/health

Health check

⌄

Request

No authentication required.

Response

Status: 200 OK

{
  "status": "ok",
  "timestamp": "2026-03-31T12:00:00.000Z"
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate the result of your request.

200 OK

Audit completed successfully

400 Bad Request

Missing or invalid query parameters

401 Unauthorized

Missing or invalid API key

403 Forbidden

Endpoint requires an active Pro subscription

404 Not Found

No audit on record yet for the requested domain

409 Conflict

Tracked-domain cap reached (5 domains per account)

429 Too Many Requests

Audit rate limit exceeded (5 audits per key per day)

502 Bad Gateway

Upstream audit service error; try again later

Admin Portal

Visit /admin_portal to manage your API keys. Sign in with Google.

Portal Features

Create keys — plaintext shown once at creation, copy immediately
View keys — creation date and last-used timestamp for each key
Revoke keys — instantly disable a key that should no longer work
Rotate keys — revokes the old key and generates a new one
Usage stats — requests today and total requests per key