AI API documentation has to explain more than endpoints. Integrators need to know which models support tools or images, how streams terminate, whether jobs can be retried, what usage fields mean, and which actions require user consent.

A generated OpenAPI reference is necessary, but it is not enough. Good documentation connects the wire format to the operational behavior of a probabilistic, metered system.

Give developers a truthful five-minute path

The quickstart should produce one successful response with the fewest safe steps:

1. create a development credential;
2. store it outside source control;
3. make one minimal request;
4. inspect the response and request ID;
5. revoke the credential.

curl https://api.example.ai/v1/responses \
  -H "Authorization: Bearer $EXAMPLE_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":"summarize","input":{"text":"Example text"}}'

Use a harmless example, a low-cost default, and a real response shape. Never tell readers to paste a production key into browser code. Link directly to managing AI API keys and secrets.

Document the application schema

For every field, state:

• type, required status, and constraints;
• default behavior;
• whether the field is stored or logged;
• compatible tasks, models, or response modes;
• whether it affects latency or cost;
• a valid and invalid example.

Separate your stable application fields from provider pass-through options. If an escape hatch exists, label its portability and support risks.

Explain response variability

Examples must not imply identical output on every run. Document finish reasons, empty or refused responses, truncation, safety handling, and the limits of structured output.

When a schema is requested, show both syntactic validation and the semantic checks the application must perform. A model returning valid JSON does not make its claims or identifiers trustworthy. The AI API design guide defines the boundary.

Treat streaming as its own reference

Publish the complete event vocabulary, not only a JavaScript snippet. For each event document:

• event name and schema;
• ordering guarantees;
• whether it may occur more than once;
• terminal and error states;
• heartbeat and timeout behavior;
• cancellation and reconnect semantics.

Include a transcript from connection through response.completed. Explain how a client should handle an unknown future event without crashing.

Document tools as security-sensitive integrations

A tool reference needs more than its JSON Schema. State:

• what the tool can change or disclose;
• required user and agent permissions;
• confirmation requirements;
• idempotency behavior;
• rate and spending limits;
• audit data;
• representative validation failures.

Make clear that model-generated arguments are proposed input. The server still authenticates, authorizes, validates, and executes the action. Link to AI application authentication and OAuth for AI agents.

Publish a model and capability matrix

Model names alone do not tell developers what works. Maintain a table for capabilities your API actually supports:

Capability	Fast alias	Capable alias	Notes
Streaming	Yes	Yes	Event format is stable
Tool calls	Yes	Yes	Parallel calls may differ
Structured output	Limited	Yes	Schema limits apply
Image input	No	Yes	Size and format limits

Distinguish your alias from the provider model resolved at runtime. Include a dated changelog for model migrations and a deprecation policy. Do not promise a provider capability you have not verified through your own adapter.

Describe jobs, webhooks, and retries together

For an asynchronous job, document every state and transition: queued, running, waiting for input, completed, failed, cancelled, and expired. State how long results remain available and whether cancellation is best-effort.

Webhook docs should include signature verification, delivery identifiers, retry schedule, duplicate delivery, ordering limits, and replay protection. Provide polling as a recovery path where practical. See webhook architecture for AI workflows and idempotency for AI agents.

Make errors actionable and safe

Each error entry should contain the HTTP status, stable application code, likely cause, retryability, safe next action, and an example with a request ID.

Separate:

• authentication and authorization failure;
• invalid input or unsupported capability;
• safety or policy rejection;
• quota and rate limits;
• provider timeout or availability failure;
• internal error.

Never require a user to share credentials or sensitive prompts with support. The AI API failures guide shows how retries and fallbacks should differ by failure class.

Explain usage, limits, and cost

Document which token or usage counts are returned, when they become final, and whether cached or tool activity is included. Clearly label estimated cost and link to the authoritative billing source.

Publish request, token, concurrency, and job limits separately. Explain whether limits apply per credential, user, tenant, model, or account. Point integrators to AI API rate limiting for client behavior.

Test documentation like product code

Documentation fails when copied examples drift. In CI:

• parse every documented JSON example;
• compile or lint SDK snippets where practical;
• run quickstarts against a controlled test environment;
• validate links and anchors;
• compare schemas with the deployed API;
• flag undocumented error codes and events.

Keep generated references and hand-written guidance in one release workflow. Date-sensitive model and pricing claims need an owner and a verification date.

Documentation checklist

• A new developer can complete a safe request in five minutes.
• Authentication examples never expose client-side secrets.
• Request, response, stream, tool, and job schemas are complete.
• Capability tables distinguish aliases from provider models.
• Error entries explain safe retry behavior.
• Usage, quotas, and estimated pricing are qualified.
• Webhook signatures, duplicates, and recovery are documented.
• Examples run in automated validation.
• Migrations and deprecations have dates and replacement paths.

Documentation is part of AI Application Architecture. It is the operational contract that keeps clients, model adapters, gateways, and security policy aligned as the underlying providers change.