Public API documentation best practices for the agent era

By the end of this guide you'll have a documentation setup that works for two audiences at once: the human developers who've always read your docs, and the AI agents that now read them too. You'll know what to publish, how to structure it, how to make examples runnable, and how to keep the whole thing from drifting out of sync with the code.

Prerequisites: an existing REST or GraphQL API, an OpenAPI spec (or the willingness to write one), and CI you can extend. Time required: 2–4 engineering weeks for the first pass, ongoing maintenance after that.

A note before we start. Public API documentation used to be a developer experience problem. It still is — but the reader profile has shifted. SDK generators, agent frameworks, and MCP servers all consume your docs as structured input. If your docs only make sense to a human squinting at a browser tab, half your consumers are already blocked.

Step 1 — Treat your OpenAPI spec as the source of truth

Every downstream artefact — reference docs, SDKs, sandbox environments, agent tool definitions — should be generated from a single OpenAPI document. Hand-written reference pages drift. Generated ones don't.

Commit the spec to the same repo as the API. Version it with the code. Fail CI when the spec and the implementation disagree.

# Validate the spec on every PR
npx @redocly/cli lint openapi.yaml

# Diff against the last published version to catch breaking changes
npx oasdiff breaking openapi.previous.yaml openapi.yaml

Expected output: zero lint errors, and a clean diff or an explicit acknowledgement of the breaking change. If either fails, the build fails. See OpenAPI specification best practices for the field-level rules that matter most when generators and agents read the spec.

Step 2 — Write descriptions that answer the questions agents ask

Human developers can guess intent from a well-named endpoint. Agents can't. They read the description field verbatim and pick tools based on it.

For every operation and every parameter, write descriptions that answer three questions: what does this do, when should the caller use it, and what shouldn't they use it for.

paths:
  /invoices/{id}/void:
    post:
      summary: Void an invoice
      description: |
        Voids an issued invoice. Use this when an invoice was sent in error
        or contains incorrect line items. Voiding is permanent and cannot
        be reversed. Do not use this to correct a paid invoice — issue a
        credit note instead. Only invoices in status 'issued' or 'overdue'
        can be voided.

That description does the work that a human would otherwise do by reading three separate pages of guidance. It also gives an agent enough context to refuse the wrong action. See OAS best practices for why the description field is now load-bearing.

Step 3 — Publish interactive examples, not just curl snippets

Every endpoint page needs a live "try it" panel. Static examples are fine for browsing; they're useless for evaluating whether a call will actually work in your account. Redocly, Scalar, Bump.sh, and Mintlify all render this from the OpenAPI spec.

Three things the interactive panel must do:

1. Prefill the caller's authentication (short-lived token, scoped to a sandbox tenant).
2. Send a real request against a real sandbox environment.
3. Show the full response — status, headers, and body — not a redacted example.

If the reader has to copy a curl command into a terminal to see what your API actually returns, your documentation is asking them to do the work generators and agents already do automatically.

Step 4 — Ship an API sandbox that mirrors production

An API sandbox is a separate environment that speaks the same contract as production, backed by seed data the caller can safely mutate. It's the single highest-leverage thing you can add to your developer experience.

Three rules for a sandbox that pulls its weight:

1. Same OpenAPI contract as production. No stubbed endpoints, no "not available in sandbox" responses. If it's in the spec, it works.
2. Deterministic seed data. Every new sandbox tenant starts with the same fixtures — invoices, customers, orders — so example requests in the docs return predictable responses.
3. Reset button. Callers should be able to wipe and reseed their sandbox tenant in one click. Agents building against the sandbox need this even more than humans.

Sandbox environments are also where agent evaluation runs. See agent evals for why a stable sandbox is a prerequisite for measuring tool-call accuracy.

Step 5 — Document authentication once, correctly

Authentication is where most public API documentation loses readers. There's a getting-started page, a security page, an OAuth page, and none of them agree on the parameter names.

Consolidate to one authentication page that covers:

• The auth methods you support (API keys, OAuth 2.1, mutual TLS).
• Which one to pick for which use case. Be explicit: "Use OAuth 2.1 with PKCE if a human end user is present. Use API keys only for server-to-server automation you fully control."
• Scope model — what each scope grants, and the least-privilege set for common tasks.
• Token lifetime, refresh behaviour, and revocation.

Agent-driven callers care about scope granularity more than human developers ever did. If your only scope is read and write, expect agents to hold far more permission than they need. OAuth for AI agents covers the delegated-access setup in detail.

Step 6 — Publish error contracts, not just error codes

A list of HTTP status codes isn't an error contract. An error contract tells the caller what to do next.

For every error your API returns, document:

• The HTTP status.
• A stable machine-readable code field (not the human message — that changes).
• Whether the error is retryable, and if so, under what conditions.
• What the caller should change to succeed.

{
  "error": {
    "code": "invoice_already_voided",
    "message": "This invoice has already been voided.",
    "retryable": false,
    "docs": "https://docs.example.com/errors/invoice_already_voided"
  }
}

The retryable flag is the single most useful field you can add for agent consumers. Without it, agents guess — and guessing means retry storms. See our rate limiting best practices for why explicit retry signals matter more as agent traffic grows.

Step 7 — Keep the docs in sync with the code, automatically

Drift is the failure mode that kills every documentation project. The fix is CI, not discipline.

Wire three checks into your pipeline:

1. Spec-implementation contract test. Every endpoint the spec describes must exist and return the schema it promises. Tools like Schemathesis or Prism generate contract tests from the OpenAPI file.
2. Breaking-change detection. Run oasdiff against the previous published spec on every PR. Block merges that break the contract without an explicit version bump.
3. Example freshness. For every code example in the docs, run it against the sandbox in CI. If it 400s, the docs are wrong.

More on this in how to detect API breaking changes.

Common pitfalls

Publishing prose without the spec. Long Markdown pages describing endpoints. Generators and agents can't parse them. Ship the OpenAPI file first, then generate the prose from it.

Sandbox environments that lie. A sandbox that returns different shapes than production is worse than no sandbox. Callers debug against the sandbox and then break in prod. Same contract or don't ship it.

One read scope for everything. Coarse scopes are a security review failure waiting to happen once agents start calling your API on behalf of end users. Scope by resource and action from day one.

Hand-rolled SDKs. Every SDK you maintain by hand is another drift surface. Use a maintained generator like Speakeasy or Fern to produce SDKs from the spec, or accept that consumers will use the raw HTTP API.

Docs that assume a human is reading. "Simply click the button below" doesn't work when the reader is an SDK generator or an agent framework. Every instruction should be machine-followable — parameter names, exact endpoints, structured responses.

What to do next

Run this on your existing docs today: pick one endpoint, and ask whether an agent could pick the right tool, format the right request, and handle a failure response — using only what's in your published documentation. If the answer is no, start with Step 2 and work forward. Everything else builds on descriptions that actually describe.