# OpenAPI

Category: [Agents & Protocols](https://seo-geo-glossary.com/en/glossary/category/agents-protocols/) › [Agent protocols](https://seo-geo-glossary.com/en/glossary/category/agents-protocols/agent-protocols/) · Also known as: OpenAPI Specification, OAS

**OpenAPI** is a language-agnostic specification format for describing HTTP APIs. An OpenAPI document, written in JSON or YAML, lists an API's endpoints, the parameters they accept and the responses they return. People and programs can then understand the API without reading its source code. "Open API" is also used for publicly available APIs in general. This entry covers the specification.

## How is an OpenAPI document structured?

The specification defines a root OpenAPI object with several parts. The Info object holds metadata such as title and version. The Paths object lists endpoints and their operations. The Components object stores reusable schemas, parameters and responses. Server and security definitions complete the document. Entry files are conventionally named `openapi.json` or `openapi.yaml`.

The specification is maintained by the OpenAPI Initiative under the Linux Foundation. It grew out of the Swagger specification, which SmartBear donated. The latest version listed at spec.openapis.org is 3.2.1, released in September 2026.

## What is OpenAPI used for?

The OpenAPI Initiative lists use cases such as API design, generating client and server code, documentation, API gateway configuration, and contract and security testing. Because the format is machine-readable, tools can process the description directly.

For discovery, RFC 9727 defines the path `/.well-known/api-catalog`, where a site can publish a machine-readable list of its APIs. Cloudflare checks for this catalog in its Agent Readiness Score.

## Example

The example uses version 3.1.0 for illustration.

```yaml
openapi: 3.1.0
info:
  title: Example API
  version: "1.0"
paths:
  /pages/{id}:
    get:
      summary: Get a page
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The page was found.
```

## Common mistakes

- **Omitting the `openapi` field.** It is required and must hold the version number of the specification the document uses.
- **Naming the entry file arbitrarily.** The specification recommends `openapi.json` or `openapi.yaml`, so tools and people can find it.
- **Using a YAML parser of a different version.** The specification recommends YAML 1.2 so that JSON and YAML convert into each other without loss.

## FAQ

**What is the difference between OpenAPI and Swagger?**
Swagger was the original name of the specification. After the donation to the OpenAPI Initiative it became the OpenAPI Specification.

**Is OpenAPI the same as REST API?**
No. A REST API is an API style. OpenAPI is a format to describe HTTP APIs, including REST ones.

## At a glance

- **Publisher:** OpenAPI Initiative (Linux Foundation)
- **Connects:** HTTP APIs with developers and tools through a machine-readable description
- **Status:** specification of the OpenAPI Initiative, current version 3.2.1 (2026-09-10)
- **License:** Apache 2.0
- **Specification:** [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)

Last checked: October 8, 2026

## Related terms

- [API](https://seo-geo-glossary.com/en/glossary/api/index.md)
- [MCP server](https://seo-geo-glossary.com/en/glossary/mcp-server/index.md)
- [Tool calling](https://seo-geo-glossary.com/en/glossary/tool-calling/index.md)
- [Agent readiness](https://seo-geo-glossary.com/en/glossary/agent-readiness/index.md)

## Sources

- [What is OpenAPI? – OpenAPI Initiative](https://www.openapis.org/what-is-openapi)
- [OpenAPI Specification v3.2.1 – spec.openapis.org](https://spec.openapis.org/oas/latest.html)
- [About the OpenAPI Initiative](https://www.openapis.org/about)
- [RFC 9727: api-catalog – IETF](https://www.rfc-editor.org/rfc/rfc9727)

---

Last updated: October 8, 2026
URL: https://seo-geo-glossary.com/en/glossary/openapi/