Skip to main content

AI glossary Operations

What is an API specification?

← All glossary terms
In short

A formal, machine-readable description of an API's endpoints, data schemas, authentication and errors, such as an OpenAPI document.

Explained

An API specification is a formal description of how an API works: which endpoints or operations it offers, what each request must contain, what each response returns, how authentication works and which errors can occur. Written in a standard, machine-readable format such as OpenAPI, often with JSON Schema for the data, it lets clients and servers agree without ambiguity. The same document drives documentation, mock servers, generated client code and contract tests. In AI systems it also matters for tool calling, because the model must produce calls that match a strict schema.

What an API specification contains

  • Operations: the paths or methods available, such as GET /orders/{id}.
  • Parameters and request bodies, with types, required fields and allowed values.
  • Responses for each status code, with their data schemas.
  • Authentication and authorisation schemes.
  • Error formats and codes.
  • Descriptions and examples that explain intent to people, and to models.

What it is used for

  • Documentation that stays in sync with the API.
  • Mock servers so that front-end and back-end teams can work in parallel.
  • Generated client and server code in several languages.
  • Contract tests that fail when an implementation drifts from the agreed contract.
  • Validation of requests and responses at runtime, for example in an API gateway.

In an API-first or spec-driven approach, the specification is agreed before the code is written.

API specifications and AI agents

When a language model calls a tool, it has to produce arguments that match a schema. Tool definitions in most AI platforms use JSON Schema, and an existing OpenAPI document can often be converted into tools for an agent. Clear names, descriptions and examples in the specification help the model choose the right operation and fill in the arguments correctly. Validating the model's calls against the schema before executing them is a basic safeguard.

Frequently asked questions

What is an API specification in simple terms?

It is a precise, structured description of what an API offers and how to use it: what to send, what you get back and what errors can happen. Both people and software can read it.

What is the difference between OpenAPI and Swagger?

Swagger was the original name of the specification and of a set of tools. The specification was donated to the OpenAPI Initiative and renamed the OpenAPI Specification; Swagger remains the name of a family of tools that work with it.

What is the difference between API documentation and an API specification?

A specification is the formal, machine-readable contract. Documentation is the human-friendly explanation, which can be generated from the specification and enriched with guides and examples.

What is JSON Schema used for?

JSON Schema describes the structure of JSON data: which fields exist, their types and which are required. OpenAPI uses it to define request and response bodies, and AI platforms use it to define the arguments of tools.

Why do API specifications matter for AI agents?

Agents call APIs as tools, and they need a precise description of each operation to do it correctly. A good specification reduces wrong calls, and validating calls against it prevents malformed requests from reaching your systems.

Where it shows up at Thinkia

Products

Further reading

Sources

Updated: 2026-10-21

Want to see how this applies to your organisation?

Talk to an AI Expert