---
title: "What Is OpenAPI 3.1? The Plain-English Definition"
description: "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."
url: https://unlockedcrm.ai/blog/what-is-openapi-3-1
canonical: https://unlockedcrm.ai/blog/what-is-openapi-3-1
category: "Definitions & Glossary"
published: 2026-07-30
updated: 2026-07-30
author: "unLocked Team"
source: unLocked CRM — AI CRM for insurance agents
---

# What Is OpenAPI 3.1? The Plain-English Definition

## 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.

<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>

<h2>Definition</h2>
<blockquote>
<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>
</blockquote>

<h2>What's New in 3.1 vs 3.0</h2>
<ul>
<li><strong>Full JSON Schema 2020-12 alignment</strong> — no more "almost JSON Schema" gotchas</li>
<li><strong>Webhooks</strong> as first-class top-level objects</li>
<li><strong>Multiple <code>type</code> values</strong> (e.g., <code>["string", "null"]</code>)</li>
<li><strong>Optional <code>paths</code></strong> — webhook-only specs are now valid</li>
<li><strong>License identifier (SPDX)</strong> support</li>
</ul>

<h2>What an OpenAPI 3.1 Spec Looks Like</h2>
<pre><code>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 }</code></pre>

<h2>What You Get From an OpenAPI 3.1 Spec</h2>
<ol>
<li><strong>Auto-generated SDKs</strong> in TypeScript, Python, Go, Ruby, Java (Hey API, OpenAPI Generator)</li>
<li><strong>Postman / Insomnia import</strong> — full collection, ready to test</li>
<li><strong>ChatGPT Custom GPT Actions</strong> — paste the URL, ChatGPT calls your API</li>
<li><strong>Mock servers</strong> via Prism — develop against your own spec before backend exists</li>
<li><strong>API gateways</strong> (Kong, Tyk, AWS API Gateway) configure themselves from the spec</li>
<li><strong>Documentation portals</strong> (Redoc, Stoplight, Mintlify) generate themselves</li>
</ol>

<h2>OpenAPI vs MCP — When to Use Which</h2>
<table>
<thead><tr><th>Use Case</th><th>Best Choice</th></tr></thead>
<tbody>
<tr><td>Calling your API from a developer's code</td><td>OpenAPI 3.1</td></tr>
<tr><td>Letting ChatGPT Custom GPT call your API</td><td>OpenAPI 3.1</td></tr>
<tr><td>Letting Claude / Cursor / agentic clients use your tools</td><td>MCP</td></tr>
<tr><td>Both human devs and AI agents</td><td>Ship both — they complement</td></tr>
</tbody>
</table>

<h2>Why It Matters for Insurance APIs</h2>
<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>


<h2>See unLocked CRM in Action</h2>
<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>

## FAQ

### undefined



### undefined



### undefined



### undefined



---

Source: [What Is OpenAPI 3.1? The Plain-English Definition](https://unlockedcrm.ai/blog/what-is-openapi-3-1) — unLocked CRM, the AI CRM built for insurance agents. Citation permitted with attribution and a link to https://unlockedcrm.ai/blog/what-is-openapi-3-1.