Skip to content
All docs

REST API and API keys

Run AuditAE from your own code with an API key and the same credit balance as the dashboard. Endpoints, prices, 402 top-ups and rate limits.

Updated View as Markdown
On this page· 7 sections

The REST API lives under /api/v1 and spends the same credit balance as the dashboard. Its full contract is published as OpenAPI 3.1 at /openapi.json. To use AuditAE from an AI client such as Claude, ChatGPT or Cursor, connect the MCP server instead: Connect Claude, ChatGPT or Cursor. The same key works for both.

Get an API key

  1. Go to API keys.
  2. Click Create key.
  3. Copy the key from the banner right away: AuditAE shows it only once. Lose it and you'll need to Rotate it, which issues a new key and revokes the old one. Revoke turns a key off for good.

A key starts with ae_live_ and acts for the workspace it was created in, spending that workspace's balance. Signing in to an AI client with OAuth always uses your personal workspace, so use a key for a team workspace.

Authentication

Send the key as a Bearer token on every request:

curl https://auditae.app/api/v1/check \
  -H "Authorization: Bearer ae_live_…" \
  -H "Content-Type: application/json" \
  -d '{"brand": "Acme", "domain": "acme.com", "prompt": "best project management tool for agencies"}'

A missing, invalid or revoked key gets 401 with a WWW-Authenticate header.

Endpoints

MethodPathWhat it doesAuthPrice
POST/api/v1/checkCheck one prompt across enginesAPI key + creditPer engine: Perplexity 5¢, ChatGPT 7¢, Google AI Overviews 9¢, Google AI Mode 10¢ (opt-in), Gemini 12¢; plus the fix-it playbook unless playbook: false, at most 12¢ (LLM usage) for each answered check that didn't cite the brand, with no rollup on a single prompt
POST/api/v1/auditsRun an auditAPI key + creditPer prompt × engine: Perplexity 5¢, ChatGPT 7¢, Google AI Overviews 9¢, Google AI Mode 10¢ (opt-in), Gemini 12¢; plus the fix-it playbook, about 12¢ per answered check that didn't cite the brand and about 45¢ per audit
GET/api/v1/audits/{id}Get an auditAPI keyFree
GET/api/v1/crawl/{id}Get a crawlAPI keyFree
GET/api/v1/crawl/{id}/checksList a crawl's checksAPI keyFree
GET/api/v1/crawl/{id}/checks/{check}Get one crawl checkAPI keyFree
GET/api/v1/crawl/{id}/compareCompare two crawlsAPI keyFree
GET/api/v1/crawl/historyList a site's crawlsAPI keyFree
GET/api/v1/crawl/scheduleGet a site's crawl scheduleAPI keyFree
PUT/api/v1/crawl/scheduleSchedule weekly or monthly re-crawlsAPI keyFree; each run 1¢ per 10 pages when it runs
DELETE/api/v1/crawl/scheduleStop a site's crawl scheduleAPI keyFree
GET/api/v1/billingGet balance and pricesAPI keyFree
POST/api/v1/billing/top-upAdd creditAPI keyFree; adds $5–$1,000 of credit
POST/api/v1/crawlCrawl a siteAPI key + credit1¢ per 10 pages crawled
GET/api/v1/crawl/settingsGet a site's default crawl settingsAPI keyFree
PUT/api/v1/crawl/settingsSet a site's default crawl settingsAPI keyFree
POST/api/v1/technicalCheck one pageAPI keyFirst 3 pages a day free, then 2¢ per page
POST/api/v1/images/optimizeOptimize imagesAPI key1¢ per 5 images optimized, rounded up per call
POST/api/v1/schema/validateValidate JSON-LDAPI keyFree
POST/api/v1/schema/generateGenerate JSON-LDAPI keyFree
POST/api/v1/entities/discoverFind a brand on Wikidata and Google's Knowledge GraphAPI keyFree

Free endpoints never touch your balance. Paid endpoints need at least 5¢ of credit (one check at the cheapest engine) to start, and bill only the work that runs. Request and response shapes for every endpoint are in /openapi.json.

Prices

  • Checks and audits: one check per prompt × engine, priced per engine: Perplexity 5¢, ChatGPT 7¢, Google AI Overviews 9¢, Google AI Mode 10¢ (opt-in), Gemini 12¢. Leave out engines to run the default engines.
  • Fix-it playbook: after the checks, AuditAE diagnoses each answered check that didn't cite your brand, billed on LLM usage. POST /api/v1/audits bills about 12¢ per answered check that didn't cite the brand and about 45¢ per audit, the per-audit part being a rollup that ranks the fixes. POST /api/v1/check bills at most 12¢ per row and no rollup; send "playbook": false to run the checks alone.
  • Audits: up to 10 prompts per call. The workspace runs at most 4 audits at once; at that cap a new audit answers 202 with status: "queued" and starts within a minute of a slot opening. Poll GET /api/v1/audits/{id} for the result.
  • Crawls: 1¢ per 10 pages crawled, billed as the crawl runs, 25 pages unless you set max_pages (up to 10,000). A crawl runs up to about 4 minutes in the request; a bigger site answers status: "running" and keeps crawling — poll GET /api/v1/crawl/{id}. It stops as partial when the balance runs out. A finished crawl carries Site Health, the theme scores and the failing checks, with the link, image and script checks and the site checks included; Core Web Vitals follow a few minutes later (cwv_state is pending until then); GET /api/v1/crawl/{id}/checks lists every check with its result and GET /api/v1/crawl/{id}/checks/{check_id} returns one check's affected URLs with evidence (?compare=new or fixed for only what changed since the previous crawl). GET /api/v1/crawl/{id}/compare compares a crawl with the one before it (or ?base= any other) and GET /api/v1/crawl/history?site_id= lists a site's crawls with their Site Health; all free. PUT /api/v1/crawl/schedule with { site_id, cadence: "weekly" | "monthly" | "off", weekday?, day_of_month?, max_pages?, notify?, dry_run? } re-crawls the site on a schedule (dry_run: true previews and quotes without saving) (GET reads it with what a run costs, DELETE stops it): free to set, each run billed per page when it runs. Crawl settings: POST /api/v1/crawl and the schedule take an optional settings object (source: site, sitemaps, sitemap_url or urls; include / exclude path masks; ignore_params; subdomains; robots_agent; device; speed; cwv_urls; exclude_checks), and POST /api/v1/crawl a urls list of up to 10,000 (or a text/plain body, one URL per line, with ?site_id=&source=urls&max_pages=); GET / PUT /api/v1/crawl/settings?site_id= read and set the site's defaults, free. See Site Audit.
  • Images: POST /api/v1/images/optimize with urls (up to 20 image URLs) or site_id (the latest crawl's images over 200 KB, largest first, 10 per call unless you set limit, paged with offset) resizes and compresses them, to WebP or in their own format, and returns a private download link per image, valid for 48 hours. 1¢ per 5 images optimized, rounded up per call; an image that barely shrinks, a skipped or failed one and a repeat within 24 hours are free. Same answer as optimize_image over MCP; see Site Audit.

All prices, the sign-up offer and top-ups are on Credits, prices and top-ups.

When you run out of credit

A paid call that the balance can't cover answers 402 with the exact call to make next:

{
  "error": "Insufficient credits",
  "balance_cents": 0,
  "required_cents": 5,
  "top_up": {
    "method": "POST",
    "url": "https://auditae.app/api/v1/billing/top-up",
    "body": {
      "amount_usd": 5
    },
    "min_usd": 5,
    "max_usd": 1000,
    "note": "Returns a Stripe Checkout URL. Give it to the account owner to pay; credit lands within seconds."
  },
  "top_up_url": "https://auditae.app/dashboard/billing"
}

POST /api/v1/billing/top-up with { "amount_usd": 20 } returns a Stripe Checkout link for the account owner to pay. Add "shared_payment_token": "spt_…" to pay directly with a Stripe shared payment token the owner approved. GET /api/v1/billing returns the balance.

The key of an agent workspace created on /api/mcp/pay that has never been funded works only on /api/mcp/pay and the two billing routes. Every other /api/v1 route answers 403 with code: "workspace_unfunded" and the same top_up object; fund it, then retry with the same key.

If the balance runs out partway through an audit, the response comes back with partial: true and out_of_credits: true, holding the cells that did run. Cells that didn't run aren't billed.

Rate limits

  • 60 requests a minute per API key.

  • 30 failed authentications a minute per IP address. Only failed attempts count, so many customers behind one office IP aren't blocked by each other.

  • 300 images an hour per workspace for image optimization, shared with optimize_image over MCP and in AEBOT, counted on the images asked for.

  • 30 checks an hour of any one site with POST /api/v1/technical, counted across every caller and shared with the free site checks and the MCP tool.

Over a limit, the API answers 429 with {"error": "rate_limited", "retry_after": <seconds>} and a Retry-After header. The same limits apply to the MCP server, which shares the key.

Not in the API yet

Not yet over REST: recurring schedules (trackers) — over MCP they're live as monitor_citations, with get_changes for what moved since the last run. Google rank tracking is live over MCP (track_keywords, list_tracked_keywords, untrack_keyword). One-off re-checks are live over MCP (schedule_recheck, get_recheck, cancel_recheck). Also still on the list: a per-site audit-history endpoint and citation-trend exports. GA4 and Search Console reads are already live over MCP (query_search_console, query_google_analytics, inspect_url) and in AEBOT. Got a request? Send it from Support or email support@auditae.app.

Try it in AuditAE

Manage API keys

Still stuck? Signed in, ask AEBOT in Documentation mode (free). Or email support@auditae.app.