API documentation is the cornerstone of discoverability. Well-structured API documentation allows an API to be understood by humans as well as machines. It lets a system understand how the API is structured, what it does, and includes invaluable metadata for further filtering and sorting.

This means that API documentation is equally vital for an API to be found, understood, and used by AI. It might even be more important, considering the rising use of APIs by AI agents.

Good API documentation is essential for AI discoverability since it helps the AI understand what HTTP commands are accepted by each endpoint and what error codes are returned if something goes wrong. With that in mind, we’ve compiled some tips and best practices to help optimize API documentation for AI discoverability.

Finding APIs and Documentation

There’s no boilerplate solution for every technical problem. This means AI needs to consider APIs from a wide variety of sources, including public API repositories, search engines, API catalogs, and internal documents.

Finding the right API is rarely straightforward. But once the AI locates an API, it needs to be evaluated. This is where API documentation comes in. Detailed descriptions tell AI what the API does, what data formats it uses, what authentication systems are in place, and any limitations it might have.

Good API documentation allows developers to speak directly to machines as well as human users. To enhance this process, generative engine optimization (GEO) is becoming increasingly important. Clear, well-defined data, articulate endpoint descriptions, parameter explanations, code snippets, sample calls, and real-world use cases all aid GEO as they provide context for picking the right API and improving understandability. llms.txt, an emerging standard similar to robots.txt but for AI, is becoming more useful for discovery, as it tells an LLM exactly what to look for instead of assessing each site path and making its best guess.

Improving API discoverability helps guarantee that the LLM always gets the most up-to-date information and data. It’s also a vital component of retrieval-augmentation generation (RAG), which makes good API documentation doubly vital as it allows AI to discover internal APIs as well as public ones, and supply the generation layer with accurate, relevant details.

The Importance of Structured Descriptions

Structured descriptions are the backbone of API discoverability. API specifications like OpenAPI and AsyncAPI act as blueprints for the API, letting people and machines alike know what to expect. Well-structured descriptions like the kind found in standardized API specifications tell AI nearly everything it needs to learn to use an API without having to scan or assess text. Not only does this improve the AI’s performance, but it also makes it more accurate and trustworthy.

For example, consider the OpenAPI specification for the /v1/account endpoint from the Stripe API:

 /v1/account:
    get:
      description: <p>Retrieves the details of an account.</p>
      operationId: GetAccount
      parameters:
        - description: Specifies which fields in the response should be expanded.
          explode: true
          in: query
          name: expand
          required: false
          schema:
            items:
              maxLength: 5000
              type: string
            type: array
          style: deepObject
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              properties: {}
              type: object
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/account'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Retrieve account

These rich descriptions inform the AI exactly how to interact with that endpoint without requiring additional resources.

Now, let’s take a quick glance at API descriptions done poorly.

paths:
  /getData:
    post:
      description: Returns stuff
      responses:
        200:
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string

Naming the endpoint /getData isn’t specific enough to be useful, to start. Descriptions like returns stuff or ok aren’t clear enough to be useful, either. They also fail to specify what happens if there’s an error. Instead, both the endpoint names and their descriptions should be descriptive for AI consumption.

Blend Natural Language and Precision

Most AI users interact with the system using natural language. That’s one of the biggest advantages of using AI in the first place. A user could ask the AI, “What are some APIs that let me send email?” and the AI will return the relevant results. API documentation is where technical and natural language meet.

To help make your APIs discoverable by AI, try to be as thorough as possible when describing your API without being excessively wordy. Descriptions that are too short, like the returns stuff example listed above, aren’t descriptive enough to be useful. However, descriptions that are overly long increase the risk of the AI becoming confused and returning incorrect results. Following a well-ordered structure and describing your API accurately will make your API discoverable by AI while remaining readable and understandable by human users.

Showcase Examples

Providing concrete, real-world examples of your API in action is another vital link between the human and the AI. Sample requests and responses let human users know the API is working how it’s supposed to. It also provides additional context for an AI, helping it to better understand the use case at hand.

To help make your API discoverable by AI, provide examples of as many of the most common functions and workflows as possible. Don’t just use generic responses, either, but provide actual examples if possible.

For instance, if you provided a bank API, an example might include using it for an everyday workflow like authenticating and retrieving an account balance. Sharing specific workflows like this helps AI find the API when it’s looking for relevant tools or resources.

To document and share these tools, many API providers are turning to Model Context Protocol (MCP). MCP lets developers embed rich metadata that describes endpoints, authentication methods, parameters, and relationships between API functions. This makes it easier for AI to understand not just what an API does, but how it connects to other APIs, data sources, or workflows.

Remain Consistent

Consistency is key for API discoverability. It’s also an essential part of API design, as it makes APIs standardized and interchangeable. There’s no reason developers and designers should be using irregular structures and conventions across their organization.

As a best practice, decide on a structure ahead of time before beginning to develop your API in earnest. This also makes API-first design possible, which brings many ancillary benefits to the organization and business.

Consistency doesn’t just apply to structure, either. Consistent naming conventions and error messages will help to make your API more discoverable by AI. This was noted in the paper Do RESTful API Design Rules Have an Impact on the Understandability of Web APIs?, which found that breaking RESTful rules and design principles made an API much more difficult to find, understand, and use. The takeaway: consistency will make your API more reliable, easier to use, and less likely to break if you make any changes.

Consider Using API Documentation Tools

API documentation has come a long way since its earliest days. This means there are all manner of handy tools for creating API documentation. Tools like Swagger UI, Redoc, or Postman Collections let you create clean, consistent API documentation every time.

Using a documentation generator is a good way to make sure that your API documentation is accurate every single time. It’s also a good way to optimize your API documentation for SEO, which will also make your API more discoverable by AI. With that in mind, using an API documentation generator is a best practice for API documentation in general.

Newer tools streamline this process even further. MCP servers like APIDog let developers automatically generate API documentation, guaranteeing that it’s always up-to-date and in keeping with the latest API documentation best practices. It can also expose your API documentation to local resources like AI coding assistants, making the API just that much more discoverable.

Version Properly

API documentation is not a one-and-done activity. It’s an ongoing process. APIs are constantly changing and evolving, and the API documentation needs to reflect that. Therefore, versioning needs to be appropriately implemented for API documentation to be discoverable and consumable by AI.

As a general best practice for making sure your API is discoverable by AI, use tagging and proper structuring to make sure that an AI interacts with the correct version of an API. Changelogs, migration guides, and deprecation notices are also important. This helps your existing users stay up-to-date with changes, as well, which makes it another best practice for API discoverability in general.

Final Thoughts on API Documentation for AI Discoverability

AI isn’t going anywhere. Taking the time, energy, and resources to make sure your API documentation is its absolute best is an investment in the future of your API.

Luckily, investing in API documentation is just a solid best practice for API designers in general, anyway. Focusing on optimizing API documentation for AI discoverability will make your API more usable for your existing users while simultaneously making it more discoverable by AI and search engines alike.

Structured data, clear definitions, consistent metadata, concise but thorough descriptions, and practical examples all help AI find the right API. It also helps improve user experience. There’s truly no reason not to spend some time and energy on optimizing your API documentation.