---
path: /v1/reference/audit
title: Start an audit
summary: POST /audit — start an AI-readiness audit of a public documentation site.
group: Reference
updated: 2026-06-22
---

# Start an audit

`POST https://agentfit.dev/audit`

Start an audit of a public API documentation site. With `?async=true` the audit is
enqueued as a durable job and the response returns immediately with a `run_id` you poll;
without it the audit runs inline and the response blocks until the report is ready
(typically 10–30 seconds).

## Request

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `base_url` | body | string | yes | Root URL of the documentation site to audit, e.g. `https://docs.stripe.com`. Must be a public `https://` URL. |
| `async` | query | boolean | no | When `true`, enqueue a durable job and return a `run_id` to poll. Recommended. |

The request body is JSON (`Content-Type: application/json`); the endpoint also accepts
`application/x-www-form-urlencoded` for HTML form posts.

### curl

```bash
curl -s -X POST 'https://agentfit.dev/audit?async=true' \
  -H 'Content-Type: application/json' \
  -d '{"base_url":"https://docs.stripe.com"}'
```

### Python

```python
import requests

resp = requests.post(
    "https://agentfit.dev/audit",
    params={"async": "true"},
    json={"base_url": "https://docs.stripe.com"},
    timeout=10,
)
run = resp.json()
print(run["run_id"], run["share_url"])
```

### JavaScript

```javascript
const resp = await fetch("https://agentfit.dev/audit?async=true", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ base_url: "https://docs.stripe.com" }),
});
const run = await resp.json();
console.log(run.run_id, run.share_url);
```

## Response

`202 Accepted` (async) returns the run handle:

```json
{
  "run_id": "019eefa7-fdb7-77ac-8c56-ad184e44ece6",
  "status": "pending",
  "poll_url": "/api/public/audit/019eefa7-fdb7-77ac-8c56-ad184e44ece6",
  "share_url": "/r/019eefa7-fdb7-77ac-8c56-ad184e44ece6"
}
```

Poll [`GET /api/public/audit/{id}`](https://docs.agentfit.dev/v1/reference/get-audit) until `status` is
`done`; the scored report is then nested under `report`.

## Errors

| Status | `code` | Meaning |
|---|---|---|
| 400 | `invalid_base_url` | `base_url` missing or not a valid URL. |
| 400 | `http_not_supported` | `base_url` is `http://`; use `https://`. |
| 400 | `not_public_address` | `base_url` resolves to a private/non-public address. |
| 429 | `rate_limited` | Per-IP request rate exceeded; see `retry_after`. |
| 429 | `site_quota` | The 24-hour per-site quota for this URL is exhausted; see `retry_after`. |

See the full [error reference](https://docs.agentfit.dev/v1/errors) for codes and retry semantics.

> The legacy `/audit/{id}` in-memory poll path is **deprecated**; use the durable
> `/api/public/audit/*` endpoints documented here.