# API agent readiness

> A one-week scored read of an API surface, docs and error handling against how AI
> agents consume them, ending in the named gaps ranked by what they cost at
> integration time. One week, $1,200, fixed.

Offered by Abdul Hannan Shaikh, Senior Technical Product Manager at APIMatic since
2021. Contact: hello@ahshaikh.com. Booking: https://calendly.com/ahspm/30min

## The problem it addresses

Agents don't read documentation the way developers do. They read the spec, the
error bodies and the examples, and they stall on the parts a person would guess
past. It's cheap to find and expensive to leave in place.

## What the week produces

- A score against a public rubric, so the method is arguable rather than asserted.
- Every gap named, across the API surface, the documentation and error handling.
- The gaps ranked by what each one costs at integration time.

The report is written for the engineers who'll fix it.

Best for API products, developer platforms, and teams wiring an agent into
something that already has customers.

## Why the claims are checkable

The score comes from A[P]Iaudit (https://api-audit.ahshaikh.com/), a free and
open-source diagnostic that reads an OpenAPI spec and names the gaps. No signup.
Source: https://github.com/ahhshaikh/api-agent-score

Separately, APIMatic published a measurement: four controlled experiments on two
open-source .NET codebases, comparing an agent working with a context layer against
one working from web search alone. Compile and runtime errors fell from 16 to 1,
tokens consumed fell 65%, development cost fell 48%, and integration ran roughly
twice as fast. Method:
https://www.apimatic.io/product/context-plugins/case-study

The APIs under test in that study are open-source codebases, not customers.

## Questions

### What makes an API agent-ready?

An agent reads the spec, the error bodies and the examples. It can't ask a
colleague what a field means, and it can't guess past a 400 that says "invalid
request". Agent-ready means the surface answers those questions on its own:
complete schemas, errors that name the field and the fix, examples that run, and
auth an agent can complete without a human in the loop.

### How is this different from a normal API review?

A normal review asks whether the API is well designed. This asks whether a machine
can integrate it without a human reading the docs, which is a different question.
Plenty of well-designed APIs fail it, usually on error bodies and on examples that
assume context the agent doesn't have.

### Do we need an MCP server?

Usually not, and that's often the first thing the read tells you. An MCP server in
front of an API that agents already stall on moves the problem rather than fixing
it. Where a server is the right answer, the read says what it needs to wrap.

### What do we get at the end?

A written report: a score against the public rubric, every gap named, and the gaps
ranked by what they cost at integration time.

### How much does it cost and how long does it take?

One week, $1,200, fixed. Scope is agreed before anything starts, and the diagnostic
the score is built on is free and open source, so it can be run first at no cost.

## Related

- Product advisory, two weeks on one product decision, $2,500 fixed:
  https://ahshaikh.com/
- Essays on agent readiness, llms.txt and MCP: https://soch.ahshaikh.com