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

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

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

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:

{
  "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} 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 for codes and retry semantics.

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