Most agent API docs list an endpoint and a request body and stop there, omitting the three things that decide whether integration works: how to handle non-deterministic output, how to retry failed tool calls, and what each request costs. Here are the seven sections an agent API doc needs, plus a skeleton and an error code table.

💡 What You Will Learn

Most agent API docs list an endpoint and a request body and stop there, omitting the three things that decide whether integration works: how to handle non-deterministic output, how to retry failed too

📜 Table of Contents

• 1. How agent APIs differ
• 2. Seven sections the doc needs
• 3. Error code split
• 4. Machine-readable documentation
• 5. Docs as tests
• FAQ

AI Agent API Documentation

Most agent API docs list an endpoint and a request body and stop, omitting the three things that decide whether integration works: how to use non-deterministic output, how to retry failed tool calls, and what a request costs.

1. How agent APIs differ

2. Seven sections the doc needs

1. Auth and quotas - key format, quota measured in requests or tokens, behavior on exhaustion
2. Input schema - fields, types, required, length caps, handling of invalid values
3. Output schema and streaming protocol - field meaning, which fields can be null, event order and termination
4. Tool inventory and permissions - what the agent may call and what each tool can touch
5. Error codes and retry semantics - retryable vs terminal, retry caps, idempotency key
6. Cost and latency expectations - typical token range and latency percentiles
7. Determinism and reproducibility - whether randomness exists and how to pin versions or seeds

3. Error code split

Because agents have side effects, blind retries can double-order or double-send - the most common integration incident.

4. Machine-readable documentation

Tool descriptions must let a model judge when to call a tool and how to fill arguments; generate that list from the OpenAPI spec. Keep a condensed interface summary for other agents to read. When code-generated and hand-written docs disagree, trust the generated one.

5. Docs as tests

Generate request samples and contract tests from the spec so examples in the docs actually run in CI.

FAQ

How to test non-deterministic output? Assert behavioral constraints: schema validity, required fields, enums, expected tools called, budget respected. Sample content quality manually on a schedule.

What extra does streaming need? Event types, ordering, termination, and how to resume after a disconnect.

How to write cost expectations honestly? Give a token range and latency percentiles for a typical request, noting variance by input length and tool count - a single average hides spikes.

Do internal agents need docs? At minimum three things: input/output schema, error and retry rules, cost accounting.

Note: check each provider's official documentation for exact capabilities and billing.