---
title: "Contracts and docs · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/contracts-and-docs
updated: 2026-10-20
licence: "All rights reserved"
---

# Contracts and docs

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

> Make an OpenAPI file the single source of truth. Test the API against it, generate docs and clients from it, and publish it for people and agents.

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/contracts-and-docs`.

## Required

- [Write the contract first](https://agentwranglers.se/playbook/api-design/contracts-and-docs/openapi-contract): Describe every endpoint, parameter, body, response and error in one OpenAPI document, kept in version control next to the code.
- [Test the API against its contract](https://agentwranglers.se/playbook/api-design/contracts-and-docs/contract-tests): Run tests that send requests and validate every response against the contract.
- [Generate docs and clients from the contract](https://agentwranglers.se/playbook/api-design/contracts-and-docs/generated-docs): Build the reference docs from the OpenAPI file, not by hand. Generating SDKs from it too is optional.

## Recommended

- [Give every endpoint an example](https://agentwranglers.se/playbook/api-design/contracts-and-docs/examples): Add a realistic request and response example to every operation in the contract.
- [Make the API easy for agents to find](https://agentwranglers.se/playbook/api-design/contracts-and-docs/agent-discovery): Link the contract from a well-known place, so AI agents and tools can find and use the API without a human.

- Previous: [API security](https://agentwranglers.se/playbook/api-design/api-security)
- Next: [Webhooks and events](https://agentwranglers.se/playbook/api-design/webhooks-and-events)
- [All chapters](https://agentwranglers.se/playbook/api-design)