OpenAPI 3.1 is the standard machine-readable specification for REST APIs — and the format AI agents like ChatGPT use to call your tools.
TL;DR
OpenAPI 3.1 is the open standard (YAML/JSON) for describing REST APIs in a machine-readable way. New in 3.1: full JSON Schema 2020-12 alignment, first-class webhooks, nullable types via type arrays. It's what powers ChatGPT Custom GPT Actions, SDK generators, and API gateways.
What Is OpenAPI 3.1?
A vendor-neutral, machine-readable specification (YAML/JSON) for describing REST APIs — endpoints, parameters, schemas, auth, examples — maintained by the OpenAPI Initiative under the Linux Foundation.
Key Takeaways
- OpenAPI 3.1 is the modern standard for documenting REST APIs
- Full JSON Schema 2020-12 compatibility ends years of subtle gotchas
- Powers Postman import, SDK generation, and ChatGPT Custom GPT Actions
- Complements MCP — OpenAPI for devs and ChatGPT, MCP for agentic clients
Direct answer: OpenAPI 3.1 is the latest version of the open-source specification for describing REST APIs in a machine-readable format (YAML or JSON). It's the standard that lets tools like Postman, ChatGPT Custom GPTs, code generators, and API gateways understand your API without reading the docs. Published in February 2021, OpenAPI 3.1 brought full JSON Schema 2020-12 compatibility and is the recommended baseline for any modern API in 2026.
Definition
OpenAPI 3.1: A vendor-neutral, machine-readable specification (YAML/JSON) for describing REST APIs, including endpoints, parameters, request/response schemas, authentication, and examples. Maintained by the OpenAPI Initiative under the Linux Foundation.
What's New in 3.1 vs 3.0
- Full JSON Schema 2020-12 alignment — no more "almost JSON Schema" gotchas
- Webhooks as first-class top-level objects
- Multiple
typevalues (e.g.,["string", "null"]) - Optional
paths— webhook-only specs are now valid - License identifier (SPDX) support
What an OpenAPI 3.1 Spec Looks Like
openapi: 3.1.0
info:
title: unLocked CRM API
version: "2026-04-01"
servers:
- url: https://api.unlockedcrm.ai/v1
paths:
/contacts:
get:
summary: List contacts
parameters:
- name: stage
in: query
schema: { type: string }
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/ContactList"
components:
schemas:
ContactList:
type: array
items: { $ref: "#/components/schemas/Contact" }
Contact:
type: object
required: [id, name]
properties:
id: { type: string }
name: { type: string }
email: { type: ["string", "null"], format: email }What You Get From an OpenAPI 3.1 Spec
- Auto-generated SDKs in TypeScript, Python, Go, Ruby, Java (Hey API, OpenAPI Generator)
- Postman / Insomnia import — full collection, ready to test
- ChatGPT Custom GPT Actions — paste the URL, ChatGPT calls your API
- Mock servers via Prism — develop against your own spec before backend exists
- API gateways (Kong, Tyk, AWS API Gateway) configure themselves from the spec
- Documentation portals (Redoc, Stoplight, Mintlify) generate themselves
OpenAPI vs MCP — When to Use Which
| Use Case | Best Choice |
|---|---|
| Calling your API from a developer's code | OpenAPI 3.1 |
| Letting ChatGPT Custom GPT call your API | OpenAPI 3.1 |
| Letting Claude / Cursor / agentic clients use your tools | MCP |
| Both human devs and AI agents | Ship both — they complement |
Why It Matters for Insurance APIs
Carriers, comparators, and CRMs that publish OpenAPI 3.1 specs become instantly programmable by any AI agent or no-code platform. unLocked CRM publishes a full OpenAPI 3.1 spec at /openapi.yaml alongside its MCP server, so agencies can choose the protocol that fits their workflow.
See unLocked CRM in Action
unLocked CRM ships a native MCP server, OpenAPI 3.1 spec, free A2P 10DLC registration, and remote SOA signing — built for the modern AI-first insurance agency. Book a 15-minute demo.
Frequently Asked Questions
Is Swagger the same as OpenAPI?
Swagger 2.0 was renamed OpenAPI 3.0+ in 2017. 'Swagger' now refers to the tooling (Swagger UI, Swagger Editor); the spec itself is OpenAPI.
Should I use OpenAPI 3.0 or 3.1 in 2026?
3.1 — full JSON Schema 2020-12 alignment, webhooks, and broader tooling support make it the right baseline.
Can ChatGPT call my OpenAPI 3.1 API?
Yes — ChatGPT Custom GPT Actions accept OpenAPI 3.1 specs directly. Paste the spec URL and ChatGPT can call your endpoints.
What's the difference between OpenAPI and GraphQL?
OpenAPI describes REST APIs (multiple endpoints, fixed responses). GraphQL is a query language with a single endpoint and client-shaped responses. Both can be useful; OpenAPI dominates AI-agent integrations.