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

# Write the contract first

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

- Level: Required
- Chapter: [Contracts and docs](https://agentwranglers.se/playbook/api-design/contracts-and-docs)
- Rule: Describe every endpoint, parameter, body, response and error in one OpenAPI document, kept in version control next to the code.
- How: Use OpenAPI 3.1 or 3.2, whose schemas are JSON Schema 2020-12. Review contract changes like code. Lint it with a tool such as Spectral or Redocly. An endpoint that follows an outside protocol, such as MCP or JSON-RPC, uses that protocol's schema as its contract instead.
- Check: The linter passes on the OpenAPI file in the build, and every route the server answers appears in it.

Example:

```yaml
openapi: 3.1.1
info: { title: Example Shop API, version: 2.3.0 }
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      parameters:
        - { name: orderId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: The order, content: { application/json: { schema: { $ref: '#/components/schemas/Order' } } } }
        '404': { description: Not found, content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } } }
components:
  schemas:
    Order: { type: object, required: [id], properties: { id: { type: string } } }
    Problem: { type: object, properties: { type: { type: string }, title: { type: string }, status: { type: integer } } }
```

**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/openapi-contract`.

- Next: [Test the API against its contract](https://agentwranglers.se/playbook/api-design/contracts-and-docs/contract-tests)
- [Contracts and docs](https://agentwranglers.se/playbook/api-design/contracts-and-docs)