{"id":"what-is-openapi-3-1","slug":"what-is-openapi-3-1","title":"What Is OpenAPI 3.1? The Plain-English Definition","excerpt":"OpenAPI 3.1 is the standard machine-readable specification for REST APIs — and the format AI agents like ChatGPT use to call your tools. Here's what it is, what changed in 3.1, and why it matters.","content":"<p><strong>Direct answer:</strong> <strong>OpenAPI 3.1</strong> 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 <strong>JSON Schema 2020-12 compatibility</strong> and is the recommended baseline for any modern API in 2026.</p>\n\n<h2>Definition</h2>\n<blockquote>\n<p><strong>OpenAPI 3.1:</strong> 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.</p>\n</blockquote>\n\n<h2>What's New in 3.1 vs 3.0</h2>\n<ul>\n<li><strong>Full JSON Schema 2020-12 alignment</strong> — no more \"almost JSON Schema\" gotchas</li>\n<li><strong>Webhooks</strong> as first-class top-level objects</li>\n<li><strong>Multiple <code>type</code> values</strong> (e.g., <code>[\"string\", \"null\"]</code>)</li>\n<li><strong>Optional <code>paths</code></strong> — webhook-only specs are now valid</li>\n<li><strong>License identifier (SPDX)</strong> support</li>\n</ul>\n\n<h2>What an OpenAPI 3.1 Spec Looks Like</h2>\n<pre><code>openapi: 3.1.0\ninfo:\n  title: unLocked CRM API\n  version: \"2026-04-01\"\nservers:\n  - url: https://api.unlockedcrm.ai/v1\npaths:\n  /contacts:\n    get:\n      summary: List contacts\n      parameters:\n        - name: stage\n          in: query\n          schema: { type: string }\n      responses:\n        \"200\":\n          description: OK\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ContactList\"\ncomponents:\n  schemas:\n    ContactList:\n      type: array\n      items: { $ref: \"#/components/schemas/Contact\" }\n    Contact:\n      type: object\n      required: [id, name]\n      properties:\n        id: { type: string }\n        name: { type: string }\n        email: { type: [\"string\", \"null\"], format: email }</code></pre>\n\n<h2>What You Get From an OpenAPI 3.1 Spec</h2>\n<ol>\n<li><strong>Auto-generated SDKs</strong> in TypeScript, Python, Go, Ruby, Java (Hey API, OpenAPI Generator)</li>\n<li><strong>Postman / Insomnia import</strong> — full collection, ready to test</li>\n<li><strong>ChatGPT Custom GPT Actions</strong> — paste the URL, ChatGPT calls your API</li>\n<li><strong>Mock servers</strong> via Prism — develop against your own spec before backend exists</li>\n<li><strong>API gateways</strong> (Kong, Tyk, AWS API Gateway) configure themselves from the spec</li>\n<li><strong>Documentation portals</strong> (Redoc, Stoplight, Mintlify) generate themselves</li>\n</ol>\n\n<h2>OpenAPI vs MCP — When to Use Which</h2>\n<table>\n<thead><tr><th>Use Case</th><th>Best Choice</th></tr></thead>\n<tbody>\n<tr><td>Calling your API from a developer's code</td><td>OpenAPI 3.1</td></tr>\n<tr><td>Letting ChatGPT Custom GPT call your API</td><td>OpenAPI 3.1</td></tr>\n<tr><td>Letting Claude / Cursor / agentic clients use your tools</td><td>MCP</td></tr>\n<tr><td>Both human devs and AI agents</td><td>Ship both — they complement</td></tr>\n</tbody>\n</table>\n\n<h2>Why It Matters for Insurance APIs</h2>\n<p>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 <code>/openapi.yaml</code> alongside its MCP server, so agencies can choose the protocol that fits their workflow.</p>\n\n\n<h2>See unLocked CRM in Action</h2>\n<p>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.</p>","category":"Definitions & Glossary","featureLink":"/mcp-server","cluster":"definitions","date":"2026-11-18","lastModified":"2026-11-18","readTime":"9 min read","author":"unLocked Team","tldr":"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.","definition":{"term":"OpenAPI 3.1","text":"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."},"keyTakeaways":["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"],"faqs":[{"q":"Is Swagger the same as OpenAPI?","a":"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."},{"q":"Should I use OpenAPI 3.0 or 3.1 in 2026?","a":"3.1 — full JSON Schema 2020-12 alignment, webhooks, and broader tooling support make it the right baseline."},{"q":"Can ChatGPT call my OpenAPI 3.1 API?","a":"Yes — ChatGPT Custom GPT Actions accept OpenAPI 3.1 specs directly. Paste the spec URL and ChatGPT can call your endpoints."},{"q":"What's the difference between OpenAPI and GraphQL?","a":"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."}]}