> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-site-auditor.md).

# 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](/api/api-crawler.md).

## 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:

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

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

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

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

```bash
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](/audit/site-auditor-guide.md). For one-page scoring, use [Page Auditor API endpoints](/api/api-page-auditor.md).