# API documentation an agent can actually use

> Document the full task: authentication, inputs, asynchronous results, errors, limits, and a verifiable outcome.

Canonical: https://byagents.dev/humans/api-documentation
Published: 2026-09-13
Reviewed: 2026-09-13
Publisher: ByAgents
Type: Guide
Level: Technical
Outcome: Identify the documentation needed for an agent to reach a first successful API result.

Useful API documentation lets an agent move from a customer task to a verified result without inventing missing steps. An endpoint list is a starting point. The complete contract includes access, request shape, completion behavior, error recovery, and the meaning of success.

## Begin with the result
For an extraction API, success is not merely receiving HTTP 200 or 202. It is obtaining the required fields in a usable form. Write a short workflow that starts with the intended input and ends with the actual output. State what the example does not cover.

A good quickstart identifies the base URL, authentication method, required parameters, content types, and response structure. It also explains the pricing unit and whether an example consumes a paid resource. Use placeholders for secrets and synthetic data for public examples.

## Close asynchronous handoffs
An API may accept a job before the result is ready. The documentation should explain how to identify that job, inspect its status, retrieve the output, and recognize terminal failure. If polling is expected, describe the permitted interval and stopping conditions.

```text
POST /jobs
→ 202 Accepted { "jobId": "example-job" }

GET /jobs/example-job
→ 200 OK { "status": "complete", "result": { ... } }
```

This fictional contract illustrates the missing handoff ByAgents checks for. It is not a live endpoint. A job identifier without a documented retrieval path leaves both a developer and an agent guessing.

## Make the specification useful
OpenAPI describes HTTP APIs through operations, parameters, schemas, responses, and security definitions. A valid document provides structure for tools to inspect, but validity alone does not prove the workflow is complete or the implementation matches. [OpenAPI 3.1.1 specification](https://spec.openapis.org/oas/v3.1.1.html).

Give operations distinct, stable identifiers and specific descriptions. Document error responses alongside successful ones. Ensure examples conform to their schemas. State whether a field is optional, nullable, or absent until a later state; these are different situations for a client.

## Explain retries before they become duplicate actions
An agent encountering a timeout should not have to guess whether a job was created or a payment occurred. Document idempotency support where it exists, how to check the original operation, and which failures are safe to retry. Do not invent idempotency support in a wrapper around an API that lacks it.

A useful error identifies what failed and, when appropriate, the next action: correct an input, reduce a batch, wait until a stated retry time, or request permission. Avoid returning secrets, internal stack traces, or unrelated customer data in an error.

## Test the journey, not just the schema
Run a representative task in an authorized environment using the published documentation. Record the inputs, requests, outputs, and failure. Check the final artifact against an expected result. Then rerun after the smallest repair.

Static contract analysis can flag a missing step before a live test. It cannot establish that credentials work, a server is available, or an extraction is accurate. Keep the output of a static diagnostic labeled accordingly.

## A maintenance habit
When the API changes, update the reference, quickstart, SDK example, and relevant tool description together. Retire outdated examples or clearly mark their version. A distribution path is only as reliable as the instructions it lands on.

## Sources

- [OpenAPI 3.1.1](https://spec.openapis.org/oas/v3.1.1.html)

## Related reading

- [MCP, registries, and getting your tools discovered](https://byagents.dev/humans/mcp-and-tool-discovery)
- [From discovery to a purchase, booking, or API call](https://byagents.dev/humans/from-discovery-to-action)
- [Measure agent discovery without fooling yourself](https://byagents.dev/humans/measuring-agent-traffic)