# REST API and API keys

Source: https://auditae.app/docs/api

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.

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](https://auditae.app/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](https://auditae.app/docs/mcp). The same key works for both.

## Get an API key

1. Go to [API keys](https://auditae.app/dashboard/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:

```bash
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

| Method | Path | What it does | Auth | Price |
|---|---|---|---|---|
| POST | `/api/v1/check` | Check one prompt across engines | API key + credit | Per engine: Perplexity 5¢, ChatGPT 7¢, Google AI Overviews 9¢, Google AI Mode 10¢ (opt-in), Gemini 12¢ |
| POST | `/api/v1/audits` | Run an audit | API key + credit | Per prompt × engine: Perplexity 5¢, ChatGPT 7¢, Google AI Overviews 9¢, Google AI Mode 10¢ (opt-in), Gemini 12¢ |
| GET | `/api/v1/audits/{id}` | Get an audit | API key | Free |
| GET | `/api/v1/billing` | Get balance and prices | API key | Free |
| POST | `/api/v1/billing/top-up` | Add credit | API key | Free; adds $5–$1,000 of credit |
| POST | `/api/v1/crawl` | Crawl a site | API key + credit | 1¢ per page crawled |
| POST | `/api/v1/technical` | Check one page | API key | Free |
| POST | `/api/v1/schema/validate` | Validate JSON-LD | API key | Free |
| POST | `/api/v1/schema/generate` | Generate JSON-LD | API key | Free |
| POST | `/api/v1/entities/discover` | Find a brand on Wikidata | API key | Free |

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](https://auditae.app/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.
- **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 page crawled, 25 pages unless you set `max_pages` (up to 250). The balance has to cover `max_pages` × 1¢ to start.

All prices, the free signup credit and top-ups are on [Credits, prices and top-ups](https://auditae.app/docs/credits).

## When you run out of credit

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

```json
{
  "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.

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.

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 or MCP: **recurring schedules (trackers)**. 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`) and in AEBOT. Got a request? Send it from [Support](https://auditae.app/dashboard/support) or email support@auditae.app.