> 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

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

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

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

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

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