A spec an agent can actually read
Technology
OpenAPI is the description of a REST API that a machine can act on: every endpoint, every parameter, every response shape, in one document. We target 3.1, because its schemas are JSON Schema rather than a dialect that is almost JSON Schema.
On CrewAI, openapi.json documents every REST endpoint, and the Model Context Protocol server exposes that same API as a set of tools. One API, two surfaces, one description both of them answer to.
Why
Why 3.1, and why we publish it
- One description behind two different surfaces
CrewAI's MCP tools mirror its public REST API, and openapi.json is what describes that API. Writing the spec first is what keeps the tool layer a mirror rather than a second implementation, quietly drifting away from the endpoints it was supposed to reflect.
- A spec drifts unless something enforces it
A description written by hand and maintained by hand stops matching the API the first week nobody remembers to update it. The spec is only worth targeting if it is generated from the code or checked against it in the build. Otherwise it is documentation that lies with authority.
- It says what, never whether
OpenAPI describes the calls and the shapes they take. It has nothing to say about who is allowed to make them. On CrewAI that answer lives in a separate document, the authorization server metadata, because a spec is a description and not a permission.
Project
Where we publish a spec
Writing
How we think about machine readable sites
How to get your website agent-ready
How to Optimize for AI Search: A Technical Guide
Generative AI is transforming online discovery, placing a new emphasis on crawlability, structured data, and site performance. Discover how to optimize your technical foundation to ensure your content is understood, trusted, and cited as an authoritative source.