What Is OpenAPI 3.1? The Plain-English Definition

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 type values (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

  1. Auto-generated SDKs in TypeScript, Python, Go, Ruby, Java (Hey API, OpenAPI Generator)
  2. Postman / Insomnia import — full collection, ready to test
  3. ChatGPT Custom GPT Actions — paste the URL, ChatGPT calls your API
  4. Mock servers via Prism — develop against your own spec before backend exists
  5. API gateways (Kong, Tyk, AWS API Gateway) configure themselves from the spec
  6. Documentation portals (Redoc, Stoplight, Mintlify) generate themselves

OpenAPI vs MCP — When to Use Which

Use CaseBest Choice
Calling your API from a developer's codeOpenAPI 3.1
Letting ChatGPT Custom GPT call your APIOpenAPI 3.1
Letting Claude / Cursor / agentic clients use your toolsMCP
Both human devs and AI agentsShip 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.