SEO audit API
The Crawlwise SEO audit API runs page audits, site crawls, and the AI crawler, schema, and vitals tools over REST. Programmable audits, crawls and tools. Every response includes x-credits-charged and x-credits-remaining. Errors are { error: { code, message, docs_url } }. Cursor pagination, never offset. Spec: /v1/openapi.json.
Auth
Authorization: Bearer cw_live_… Keys live at /account/api. Using this from an agent? Start at /agents. From a terminal: npx crawlwise audit calls this API; npx crawlwise ai-crawlers uses the free tool endpoints and needs no key. Starter and the free plan cannot create keys; the API starts at Growth, $49.99/mo.
Errors
Every error is { error: { code, message, docs_url } }. The message is written to be shown to a person as it is.
| Code | Status | What to do |
|---|---|---|
UNAUTHORIZED | 401 | Send Authorization: Bearer cw_live_… with a key from /account/api. A revoked key also answers 401. |
PLAN_REQUIRED | 403 | The API starts at Growth. Upgrade at /plans. |
FORBIDDEN | 403 | The key lacks the scope this path needs. Create a key with that scope. |
ACCOUNT_HOLD | 403 | The account is on hold. Contact support. |
LIMIT | 403 | A plan limit, such as the number of sites or crawl pages. The message names it. |
NO_CREDITS | 402 | Not enough credits for the estimate. Top up, or estimate a smaller job with POST /v1/estimate. |
RATE_LIMITED | 429 | This key has used its calls for today. Wait for Retry-After (seconds), or use another key. |
TOO_MANY_RUNNING | 429 | Too many audits or crawls are running on this account. Wait for one to finish. |
CONCURRENT | 409 | A crawl is already running for this site. |
RUNNING | 409 | The job is still running. Poll it until status is complete. |
NOT_RUNNING | 409 | The job is not running, so it cannot be cancelled or continued. |
INVALID | 400 | The request body is not valid. The message says which field. |
EMPTY | 400 | A required value was empty. |
TOOL_FAILED | 400 | The tool could not run on that input: a private or malformed URL, a page that did not answer, or nothing to validate. The message says which. |
NOT_FOUND | 404 | No such path, or no such audit, crawl or site on this account. |
UNKNOWN_TOOL | 404 | No tool by that name. |
NO_PRICE | 404 | That operation has no price, so it cannot be run or estimated. |
METHOD | 405 | Use the method listed for the path below. |
CREDITS | 503 | Credits could not be reserved. Retry in a moment; nothing was charged. |
JOB | 503 | The job could not be started. Retry in a moment; nothing was charged. |
CRAWL | 503 | The crawl could not be started. Retry in a moment; nothing was charged. |
INTERNAL | 500 | Something failed on our side. Retry, and contact support if it keeps happening. |
Credits
Headers x-credits-charged and x-credits-remaining are on every response. POST /v1/estimate never charges and never creates a job.
Webhooks
HMAC-SHA256 over id.timestamp.body, headers webhook-id, webhook-timestamp, webhook-signature: v1,<base64>. Same scheme as Dodo.
Paths
| Path | Methods |
|---|---|
/v1/audits | POST, GET |
/v1/audits/{id} | GET |
/v1/crawls | POST |
/v1/crawls/{id} | GET |
/v1/crawls/{id}/pages | GET |
/v1/crawls/{id}/links | GET |
/v1/sites | GET, POST |
/v1/sites/{id} | GET, PATCH |
/v1/tools/ai-crawlers | POST |
/v1/tools/agent-readiness | POST |
/v1/tools/bot-verify | POST |
/v1/tools/schema-validate | POST |
/v1/tools/vitals | POST |
/v1/credits | GET |
/v1/estimate | POST |
/v1/openapi.json | GET |