How to Give an AI Coding Agent Your API Docs

To give an AI coding agent your API docs, put a machine-readable spec in the repository, point the agent at it in your instructions file, and give it a way to check a call against the spec before it writes the call. Pasting a documentation page into the chat window is the version that works once and then rots.

The problem this solves is specific. An agent writing against an API it half-remembers from training will produce code that looks correct, uses parameter names from an older version, and fails at runtime with an error that mentions none of that. Every hour you spend on this is an hour you do not spend on inventing APIs that do not exist.

Which API docs you actually mean

Three different things get called "API docs" and they need different treatment.

Your own internal API. You control the source of truth. This is the easy case and the one with the highest payoff.

A third-party API you consume. Stripe, Twilio, your payment provider, your email vendor. You do not control it, it changes, and the agent's training data has an old version of it.

A library or SDK. Function signatures rather than HTTP endpoints. Type definitions do most of the work here if your language has them.

The techniques below apply to all three, in decreasing order of how much control you have.

Step 1: get a machine-readable spec into the repo

A prose documentation page is the worst format for this. It is long, it is mostly examples, and the agent has to infer the contract from the narrative.

An OpenAPI or GraphQL schema is the opposite. It is compact, it is unambiguous, and every field is typed. Commit it:

docs/
  api/
    internal-api.openapi.yaml     # your own service
    stripe-2026-08-27.openapi.json # pinned vendor version

Two details matter more than they look.

Pin the vendor version in the filename. When the agent reads stripe-2026-08-27, it knows what it is looking at, and when you upgrade, the diff between two files is the migration you need to review.

Trim aggressively. A full vendor OpenAPI file can run to megabytes covering hundreds of endpoints you will never call. Extract the six endpoints you use. A 400 line spec the agent reads completely beats a 40,000 line spec it samples from.

Step 2: tell the coding agent the API docs exist

An agent will not read a file it does not know about. This belongs in your instructions file, alongside everything else about how the repo works, as covered in how to write an AGENTS.md file.

The instruction that works is specific about when to read, not just what exists:

## API contracts

Before writing or editing any code that calls an external API,
read the matching spec in docs/api/.

- Our own service: docs/api/internal-api.openapi.yaml
- Stripe: docs/api/stripe-2026-08-27.openapi.json

Do not infer endpoint paths, parameter names, or response shapes
from memory. If the spec does not contain the endpoint you need,
stop and say so rather than guessing.

The last sentence does the heavy lifting. Without an explicit permission to stop, a model asked for something not in the spec will invent a plausible endpoint, because producing an answer is the default behaviour. Explicitly licensing "I cannot find this" changes the outcome.

Step 3: make the contract checkable, not just readable

Reading is advisory. Verification is binding. The strongest version of this gives the agent a command that fails when the code and the spec disagree.

Options, roughly in order of effort:

• Generate a typed client from the spec. If your language has types, a generated client turns a wrong parameter name into a compile error the agent sees immediately. This is the highest-leverage option by a wide margin.

• Contract tests in CI. Validate requests and responses against the schema during the test run. The agent runs the tests, the tests fail, the agent fixes it without you in the loop.

• A lint step. Even a script that greps for endpoint strings not present in the spec catches the common case.

The principle is general: a feedback signal the agent can act on unattended is worth more than any amount of instruction it has to remember.

Step 4: handle the vendor drift problem

Your pinned spec will go stale. Two habits keep this cheap.

Subscribe to the vendor's changelog and treat a spec update like a dependency update: a small pull request, on its own, with the diff visible. This is exactly the situation described in why your AI coding agent keeps recommending deprecated packages, and the fix is the same, an authoritative local file that beats stale training data.

Record the version you are on in the instructions file too, so the agent has a date to reason about. "The Stripe spec in this repo is from 27 August 2026" is a useful fact for a model whose training data stopped months earlier.

What not to do

Do not paste the docs into every prompt. It burns context on material the agent needs for one function call in ten, and it disappears the moment the session resets.

Do not point the agent at the vendor's documentation URL and let it browse. It works, it is slow, and it produces different results on different runs depending on what the page rendered. A committed file is deterministic.

Do not skip the internal API because you wrote it. Your own service is the one the model has no training data for at all, which makes the spec more valuable there, not less. The same argument applies to your internal library and to your design system.

FAQ

What if the API has no OpenAPI spec?

Write a minimal one covering only the endpoints you use. An afternoon of work produces a file that pays for itself the first time the agent gets a parameter right without being told.

Should the spec live in the repo or somewhere central?

In the repo. An agent working on a checkout has that checkout. Anything requiring a network call to a wiki is a step that will sometimes be skipped.

Does this work for GraphQL?

Better than for REST, since the schema is already the contract and introspection gives you a current copy. Commit the generated SDL and treat it exactly like an OpenAPI file.

How much of a large vendor spec should I include?

Only the operations you call, plus the shared schema objects they reference. If you cannot skim it in a minute, it is too big for the agent to use reliably.

Does this replace tests?

No. It reduces the class of failure where the code is wrong about the interface. Tests catch the class where the code is wrong about your intent. You want both, and the broader setup is in AI coding tools.