# AgentFit API — full documentation

> The complete developer documentation for the AgentFit public API in one file, intended
> for LLMs and agents. AgentFit audits public API documentation against a 30-criteria
> AI-readiness rubric and returns a deterministic 0–100 report. No LLM calls at run time;
> the score is reproducible byte-for-byte.

## Overview

AgentFit takes a documentation base URL (for example `https://docs.stripe.com`) and scores
the site from 0 to 100 across six categories — Discovery, Page artifacts, API spec, Content,
Hygiene, and Agent Surface — with concrete HTTP evidence for every one of the 30 criteria.
You can run an audit over the HTTP API, the `agentfit` command-line tool, or the remote MCP
server.

## Authentication and limits

The public audit endpoints are unauthenticated. They are rate limited per IP and per target
URL, with a 24-hour per-site quota; throttled requests receive HTTP 429 with a `Retry-After`
header. The MCP server uses OAuth 2.1 with anonymous auto-consent (no sign-up) and issues a
short-lived bearer token.

## HTTP API

Start an audit (asynchronous, recommended):

```
POST https://agentfit.dev/audit?async=true
Content-Type: application/json

{"base_url": "https://docs.stripe.com"}
```

The response is `{"run_id", "status":"pending", "poll_url", "share_url"}`. Poll the run until
it is done:

```
GET https://agentfit.dev/api/public/audit/RUN_ID
```

When `status` is `done`, the report is nested under `report` with `total_score` and a
per-criterion breakdown. History and diff endpoints are available at
`/api/public/audit/{id}/history` and `/api/public/audit/{id}/diff`.

The complete machine-readable contract — every path, parameter, response schema, and error
code — is published as OpenAPI 3.1 at https://docs.agentfit.dev/openapi.yaml and https://docs.agentfit.dev/openapi.json.

## Errors

Most errors return a JSON body `{"error": "...", "code": "..."}` with an appropriate HTTP
status. Codes include `invalid_base_url`, `not_public_address`, `http_not_supported`,
`not_found`, `not_done`, `audit_failed`, `rate_limited`, `site_quota`, `method_not_allowed`,
and `internal`. Rate-limit/quota responses (429) include a `Retry-After` header; clients
should back off and retry. A `503` is an edge (CDN/proxy) condition, also retryable.

## CLI

```
agentfit audit https://docs.stripe.com --format both
```

## MCP server

AgentFit hosts a remote, OAuth-protected MCP server at https://docs.agentfit.dev/mcp. Connect it to an
agent client with no sign-up (the OAuth step auto-approves):

```
claude mcp add --transport http agentfit https://docs.agentfit.dev/mcp
```

Tools: `audit(base_url, format)` starts an audit; `get_report(run_id)` fetches the result.
The scope is `agentfit:audit`. Discovery follows RFC 9728 / RFC 8414 at
https://docs.agentfit.dev/.well-known/oauth-protected-resource and
https://docs.agentfit.dev/.well-known/oauth-authorization-server.

## Rubric

The six categories AgentFit scores are A. Discovery (llms.txt, sitemap, machine-readable
files), B. Page artifacts (Markdown companion, JSON-LD, semantic HTML), C. API spec (OpenAPI
coverage + quality), D. Content (code samples, error docs, glossary), E. Hygiene
(server-rendered content, live links), and F. Agent Surface (llms discovery, WebMCP, MCP server, accessibility). This
documentation site is itself built to satisfy that rubric.