Site Auditor 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 usage

• site-auditor:read lists projects, reads results, and estimates usage impact.
• site-auditor:write creates projects, starts or cancels crawls, and permanently deletes projects.

Site Auditor is included in full-platform pooled usage. Larger page ceilings have a greater usage impact, so check the current windows and estimate the requested scope before starting. Cancelled and errored crawls do not consume completed-work usage.

Estimate before starting:

curl "https://app.rankability.com/api/agent/v1/usage/estimate?operation=site_audit_run&max_pages=500" \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

{
  "operation": "site_audit_run",
  "metering_model": "pooled_usage",
  "included": true,
  "usage_impact": { "level": "high", "included": true },
  "usage": { "general_remaining_percent": 72, "burst_remaining_percent": 88 }
}

MCP callers can use site_audit_estimate or estimate_cost with operation: "site_audit_run". Both calls are read-only and start no work. The older /site-auditor/credit-estimate route remains available only to legacy metered contracts; pooled accounts receive 410 credit_estimate_retired with the replacement path.

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/projects/:project_id/pages/:page_id	site-auditor:read	Read one page’s summary, content evidence, or selected fields
GET	/usage/estimate?operation=site_audit_run	site-auditor:read	Estimate pooled usage impact 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 usage is checked or a project is created. Start with the smallest useful scope because large crawls take longer and have a greater usage impact.

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

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	Usage
pending	Project exists but crawl has not started	Not completed
crawling	Pages are being discovered and fetched	In progress
analyzing	Crawled pages are being evaluated	In progress
completed	Pages and issues are available	Included in pooled usage
cancelled	An authorized caller stopped the crawl	No completed-work usage
error	The crawl failed	No completed-work usage

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. Findings include severity and lifecycle totals plus grouped issue types, affected-page counts, and a bounded sample of affected URLs. 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).

Full project reads accept a comma-separated page_fields selection of up to 40 supported fields. Omitting it preserves the earlier Agent API response, while MCP sends a compact explicit selection that excludes analyzed_text. Select only the fields needed by the consumer.

For page-body evidence, first get the page ID from the full inventory, then read that page alone:

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

view=summary is compact. view=content adds the analyzed text and duplicate-content passages and related URLs. view=full returns all stored page fields. A comma-separated fields query, also capped at 40, overrides those presets. The page must belong to the requested project, and the project must belong to the authenticated organization.

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.
• 429 usage_limit_reached — the account’s pooled on-demand window has reached its current limit; wait until retry_at.
• 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.