Site Auditor API

Create, monitor, cancel, read, and delete Rankability Site Auditor projects through the customer Agent API.

Use the Site Auditor API for a full-site crawl that produces a project summary, crawled-page records, and detected audit issues. It reuses Rankability's Site Auditor pipeline and is different from the raw bounded Crawl API.

Scopes and billing

• site-auditor:read lists projects, reads results, and estimates cost.

• site-auditor:write creates projects, starts or cancels crawls, and permanently deletes projects.

A completed crawl costs 1 credit per 5 successfully crawled pages. Rankability checks whether the organization can afford the requested maximum before starting, but does not reserve credits. It charges once after successful completion based on actual pages crawled. Cancelled and errored crawls cost 0.

Estimate before starting:

curl "https://app.rankability.com/api/agent/v1/site-auditor/credit-estimate?max_pages=500" \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

{ "max_pages": 500, "estimated_credits": 100 }

MCP callers can use either site_audit_estimate for this Site Auditor-specific calculation or estimate_cost with operation: "site_audit_run". Both calls are read-only and create no project or reservation.

Routes

Method	Path	Scope	Purpose
POST	/site-auditor/projects	site-auditor:write	Create a project and start its first crawl
POST	/site-auditor/projects/:project_id/crawl	site-auditor:write	Re-crawl an existing project
POST	/site-auditor/projects/:project_id/cancel	site-auditor:write	Cancel an in-progress crawl
DELETE	/site-auditor/projects/:project_id	site-auditor:write	Permanently delete a non-running project and its data
GET	/site-auditor/projects	site-auditor:read	List projects
GET	/site-auditor/projects/:project_id	site-auditor:read	Read status, a bounded summary, or paginated pages and issues
GET	/site-auditor/credit-estimate	site-auditor:read	Estimate cost without starting work

Prefix every path with https://app.rankability.com/api/agent/v1.

Create and start an audit

curl -X POST https://app.rankability.com/api/agent/v1/site-auditor/projects \
  -H "Authorization: Bearer rk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "name": "Example technical audit",
    "client_id": "CLIENT_UUID",
    "max_pages": 500,
    "max_depth": 10,
    "check_external_links": false
  }'

domain is required. Rankability removes a leading protocol and trailing slash. name and client_id are optional. Every Site Auditor entry point accepts max_pages from 1–1,000 and max_depth from 1–50; defaults are 500 and 10. Requests outside those bounds are rejected before credits are checked or a project is created. Start with the smallest useful scope because large crawls take longer and raise the affordability check.

The HTTP 201 response returns immediately with project_id, status: "crawling", the effective configuration, progress counters, and estimated_credits.

Poll and interpret status

curl "https://app.rankability.com/api/agent/v1/site-auditor/projects/PROJECT_ID?view=status" \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

Poll with backoff until a terminal state:

Status	Meaning	Billing
pending	Project exists but crawl has not started	Not charged
crawling	Pages are being discovered and fetched	Not charged
analyzing	Crawled pages are being evaluated	Not charged
completed	Pages and issues are available	Charged for pages crawled
cancelled	An authorized caller stopped the crawl	No charge
error	The crawl failed	No charge

Use view=status while polling; it returns only the project and progress counters. The default view=summary adds bounded findings and verification totals without loading the page and issue inventories. Use view=full only when you need records, and paginate them independently with page_limit, page_offset, issue_limit, and issue_offset (default 5, maximum 100 per collection).

Every list and full-detail pagination block includes total and has_more. Agent API audit payloads use recursively normalized snake_case by default, including nested issue and page evidence. Send naming=legacy only for backward compatibility with the earlier mixed-casing payload.

verification_summary.unverified means the initial crawler detected the finding but nobody has performed a later live recheck. It does not mean the original finding lacked crawl evidence. Historical projects can remain entirely unverified until findings are explicitly checked or a new crawl supplies fresh evidence.

Project counters distinguish pages found, crawled, and analyzed. An unavailable page or an issue count of zero is not proof that the whole site is healthy; review crawl coverage and page failures.

List, re-crawl, cancel, and delete

GET /site-auditor/projects accepts client_id, status, limit up to 100, and offset. Its pagination includes the matching project total.

Use POST /site-auditor/projects/:project_id/crawl to start a fresh crawl with the stored configuration. A running crawling or analyzing project returns 409 conflict.

Use the cancel endpoint only while a crawl is running. If the crawl finishes during cancellation, Rankability returns 409 rather than overwriting a completed result.

Deletion is permanent and removes the project, pages, issues, and related audit records. It refuses to delete a running crawl; cancel first, confirm the terminal state, and then delete only when removal is intentional.

Common failures

• 400 invalid_input — invalid fields, status filter, or project ID.

• 402 insufficient_credits — the requested crawl ceiling is not affordable.

• 404 not_found — the client or project is outside the organization or absent.

• 409 conflict — a crawl is running, already finished during cancellation, or must be cancelled before deletion.

For the in-app interpretation workflow, see Using Site Auditor. For one-page scoring, use Page Auditor API endpoints.