OpenAPI for AI agents
An OpenAPI document describes an HTTP API in a machine-readable form: its endpoints, the parameters each takes, the shape of each response and how to authenticate. An agent can read one to learn how to call an API it has never seen.
- Listed services with an OpenAPI description
- 23
- Sites serving a real ai-plugin.json
- 75 of 1,504
From an API description to tools
Agent frameworks and several assistant platforms can turn the operations in an OpenAPI document into tools: the operation's identifier becomes the tool's name, its summary and description tell the model when to use it, and its parameter schema becomes the tool's input. The model then fills in the parameters, and the platform makes the HTTP request.
The plugin manifest
The /.well-known/ai-plugin.json manifest was introduced with ChatGPT's plugin system in 2023: it named the service, described it for the model and pointed to an OpenAPI document. That plugin system has since been replaced, but some sites still serve the file, and it still says where their API description is.
OpenAPI and MCP
OpenAPI describes any HTTP API, whoever calls it. MCP is a protocol made for assistants: the server lists its tools when the client connects, and the client calls them. Many MCP servers are a thin layer over an API that also has an OpenAPI description, and tools exist that generate one from the other.
What makes a description agent-friendly
Clear operation identifiers and descriptions written for someone who has never seen the API; examples; enumerations for allowed values; documented errors; the authentication scheme declared, not only explained in prose; and small operations that each do one thing. A published, stable URL for the document lets agents and directories find it.
Services with an OpenAPI description · Services with a public API · Browse the directory →
More: What is an MCP server? · What is llms.txt? · How AI assistants find and book travel · How listings are verified · MCP transports: stdio, Streamable HTTP and SSE · Remote or local: which kind of MCP server to use · How to add an MCP server to an AI assistant · What is the official MCP Registry? · What goes in an llms.txt file · How AI assistants find travel availability · Before you connect an MCP server: a checklist