In years gone by, API specifications and developer portals were created for developers’ eyes only. It wasn’t unusual for them to include the occasional joke or pop culture reference, or omit context that any qualified API consumer would easily be able to infer.

While the introduction of standards like OpenAPI has already systematized and sanitized the production of API specifications, outlining a basic structure that all descriptions must follow to qualify, the art of API design retains a few quirks. Take Max Kolyubyakin’s whimsical guide to including easter eggs in API responses, for example. In the wake of AI, those days are gone.

At our Platform Summit 2025, Amadeus’ Anna Tsolakou and Hongliu Cao joined us to talk about how LLMs are changing API specifications. They focused on the use of AI for modifying existing specs, but that’s only half the story. As AI usage increases, more of those quirks may need to be ironed out to make specifications as readable by machines as by humans.

Below, as well as summarizing some of their key findings and actionable tips, we’ll look at a few of the ways in which LLMs are fundamentally changing how specs are created and consumed.

Putting the “Specific” in Specification

Given that agentic access to APIs is already on the rise, we need to prepare for the inevitability of agents consuming documentation. If we fail to do so, we risk agents ignoring our APIs, hallucinations around what they can do, or abusing them by disregarding the API contract.

In our guide to optimizing API documentation for AI discoverability, which covers the practice in more detail, we identified the importance of the following concepts:

• Well-structured descriptions
• Precise, but natural, language
• Sample requests and responses
• Consistency and accuracy (such as proper versioning)

The good news is that, thanks to the standardization offered by formats like OpenAPI, many existing specifications already conform to the best practices of creating machine-readable documentation. That said, machine-readable doesn’t necessarily mean machine-optimized.

However, as we’ll see below, some obstacles have previously made it (and, in some instances, continue to make it) difficult for AI and API specifications to interface.

Maintaining API Specifications at Scale Using AI

Tsolakou kicks off her talk with a common problem: “When you have an existing API that you want to update with a new feature, you need to update your specification as well.” Not a problem in and of itself, until you’re working at scale with hundreds (or even thousands) of APIs.

She outlines how Amadeus has developed a system to maintain API specifications using an AI-powered chatbot. On the surface, it sounds simple enough:

“The chatbot receives as its input the specification file, as well as the query, and what you receive as an output is a new API specification based on the one that you gave as input.”

But there’s a little more to it: “We have to build a prompt that includes how to properly handle the input we gave,” she says, “as well as the output that we expect.” Not something you can quickly hand off to the standard iteration of ChatGPT, in other words.

So why spend the time implementing it?

As well as minimizing manual efforts at scale and enforcing standards or company guidelines, Tsolakou highlights that this process empowers users who may not be familiar with API design to modify specifications without the need for any in-depth technical knowledge. Of course, you’ll probably want someone who does have that know-how to vet the output.

It’s an interesting glimpse of what the future of modifying API specifications might look like, and it’s not difficult to imagine a world in which we could use AI for the initial creation of documentation, too. Indeed, tools like Theneo and Mintlify are already doing just that.

A Few Hurdles of Using AI With API Specifications

Cao observes that it’s only recently that we’ve been able to use LLMs for tasks like this, and the practices are still maturing. One downside is token bloat, as API specifications can be hundreds or thousands of tokens in a single file. However, this is becoming less of a concern, says Cao:

“Luckily, this year we have seen a lot of progress. Input token limits have risen from 8,000 tokens to between 128,000 and 1 million. Output has risen from 4,000 tokens to between 64,000 and 128,000.”

Although he highlights some other challenges of using LLMs operating on a large context to generate content:

• Performance degradation: Models degrade significantly as input length increases.
• Lost in the middle: Output is strong at the beginning and end of outputs, but weak in between.
• Generation failures: LLMs aren’t equipped to meet the demands of long-form text generation.

Not to mention the fact that, before the introduction of specialized coding tools like Cursor, Replit, GitHub Copilot, and others, most AI tools were built to work with text inputs and outputs, not code.

Cao describes how Amadeus has moved towards structural splitting based on the hierarchy of large files like API specifications, using a combination of high-level structure and chained summarizations to generate prompts for AI tools that enable the modification of individual sections rather than the entire specification in one go.

It’s reminiscent of a talk that Plaid’s Todd Kerpelman gave at our 2024 Austin Summit, which delved into the concept of improving documentation with an AI chatbot. In that talk, Kerpelman described how his team used an embeddings model to break down documentation, help center articles, sample code, and so on.

That’s sort of the reverse of the process described by Tsolakou and Cao, but both underline the fact that having the right inputs (your existing specification in this case) in the right format is an absolutely vital step in this process. As is using a tool that can handle vast documentation.

The Future of API Specifications Is Machine-Ready

In a previous post on agent experience (AX), we wrote that “Artificial intelligence tools are bad at inferring context or reading between the lines,” and that “content designed for consumption by AI should look less like a blog post and more like a legal contract. Great agent experience is all about being as clear and predictable as possible.”

Where possible, we need to eliminate assumptions that only make sense to human readers. LLMs aren’t as forgiving of undocumented constraints, inconsistencies, or vague descriptions as a human reader might be. If you’re struggling with that, we can lean on AI tools — it makes sense that AI would know what AI likes, right? — for identifying some of these gaps.

When we covered AI assistants for API developers, for example, we identified LintGPT as a useful tool for its ability to automate the creation of an API style guide, enforce specification standards, and even catch breaking changes before deployment.

API specifications are no longer just documentation. They’re living contracts with machines, which increasingly have the power to read and interact with said contracts. Improving clarity, consistency, and precision might create a few initial headaches, but it opens the door to smarter tooling, faster iteration, and APIs taking pride of place in an increasingly AI-driven ecosystem.