OpenAPI Examples and Tags
Are the Missing Link Between
Your APIs and AI Agents
APIDays Amsterdam — OpenAPI Track
Kin Lane • API Evangelist • [email protected]
API Evangelist
Technology, business, and politics of APIs → Standards → OpenAPI → AsyncAPI → JSON Schema → Spectral → Discovery → Governance → Government → Healthcare → Stories → Opinions → Rants → Capabilities → Conversations → Guidance → Policies → Rules → Vocabularies → Evangelism → Critic
OpenAPI
openapi: 3.1.0
info:
title: Customers API
version: 1.0.0
description: Manage customer records
paths:
/customers/{id}:
get:
summary: Get a customer
operationId: getCustomer
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
openapi: 3.1.0
info:
title: Customers API
version: 1.0.0
description: Manage customer records
components:
schemas:
Customer:
type: object
required: [id, name, email]
properties:
id:
type: string
name:
type: string
email:
type: string
format: email
createdAt:
type: string
format: date-time
Swagger → Info → Servers → Paths → Webhooks → Components → Security → Tags → ExternalDocs → Schemas → Responses → Parameters → Examples → RequestBodies → Headers → SecuritySchemes → Links → Callbacks → Documentation → SDKs → Clients → MCP → Mocks → Tests → Gateways → Security
OpenAPI Examples
paths:
/customers:
post:
summary: Create a customer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
examples:
acme:
summary: Enterprise customer
value:
name: Acme Industries
email: [email protected]
plan: enterprise
indie:
summary: Indie developer
value:
name: Jane Dev
email: [email protected]
plan: free
responses:
'200':
description: Customer created
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
examples:
acme:
summary: Enterprise customer
value:
id: CUST-000142
name: Acme Industries
email: [email protected]
plan: enterprise
createdAt: '2026-05-14T10:05:00Z'
indie:
summary: Indie developer
value:
id: CUST-000143
name: Jane Dev
plan: free
Examples → Schemas → Synthetic → Mocks → Use Cases → Data → Requests → Responses → Parameters → Sandboxes → Scenarios → Samples → Dynamic → Static → Snapshots → Recipes → Templates → Rich
OpenAPI Tags
openapi: 3.2.0
info:
title: Customers API
version: 1.0.0
tags:
- name: customers
summary: Customer profiles
externalDocs:
url: https://docs.example.com/customers
- name: billing
summary: Invoicing and payments
externalDocs:
url: https://docs.example.com/billing
- name: support
summary: Customer success
- name: notifications
summary: Customer comms
paths:
/customers:
post:
summary: Create a customer
tags:
- customers
responses:
'201':
description: Created
/customers/{id}/invoices:
get:
summary: List invoices
tags:
- billing
- customers
responses:
'200':
description: OK
Tags → Vocabulary → Domains → Groups → Categories → Semantics → Boundaries → Operations → Scope → Context → Tools → Discovery → Search → Documentation → SDKs → Gateways → Engines → Pools
OpenAPI Overlays
overlay: 1.0.0
info:
title: Enrich tags with AI context
version: 1.0.0
actions:
- target: "$.tags[?(@.name=='customers')]"
description: Add agent context to tag
update:
description: >-
Customer profile operations.
Use for identity and account
lookups by agents.
x-agent-pool: customer-ops
- target: "$.tags[?(@.name=='billing')]"
description: Add scope to billing tag
update:
description: >-
Invoicing and payment ops.
Requires financial scope.
x-scope: financial
x-agent-pool: billing-ops
# No changes to openapi.yaml # Apply at build time (CI) openapi-overlay apply \ --base openapi.yaml \ --overlay ai-context.yaml \ --output openapi-ai.yaml # Apply per environment openapi-overlay apply \ --base openapi.yaml \ --overlay prod-overlay.yaml \ --output openapi-prod.yaml # Validate overlay targets openapi-overlay validate \ --base openapi.yaml \ --overlay ai-context.yaml
Overlays → Non-Destructive → Additive → JSONPath Targets → Update → Remove → Layered → Environment-Specific → AI Context → Build Time → Governance → Distribution → Versioning
Context
# OpenAPI as MCP tool context
/customers/{id}:
get:
summary: Get a customer
description: |
Retrieve a single customer.
Call when the user mentions a
specific customer or owner.
operationId: getCustomer
parameters:
- name: id
in: path
required: true
description: Customer id
schema:
type: string
pattern: '^CUST-[0-9]{6}$'
examples:
enterprise:
value: CUST-000142
indie:
value: CUST-000143
# OpenAPI as sandbox mock context
/customers/{id}:
get:
summary: Get a customer
responses:
'200':
content:
application/json:
examples:
enterprise:
summary: Enterprise
value:
id: CUST-000142
name: Acme Industries
plan: enterprise
indie:
summary: Indie dev
value:
id: CUST-000143
name: Jane Dev
plan: free
Context → Circumstance → Environment → Situation → Conditions → Scenario → Landscape → Perspective → Vantage → Standpoint → Engineering → OpenAPI → Tags → Tag Groups → Scope → Tools
Sandboxes
paths:
/customers:
post:
summary: Create a customer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
examples:
acme:
summary: Enterprise customer
value:
name: Acme Industries
email: [email protected]
plan: enterprise
indie:
summary: Indie developer
value:
name: Jane Dev
email: [email protected]
plan: free
responses:
'200':
description: Customer created
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
examples:
acme:
summary: Enterprise customer
value:
id: CUST-000142
name: Acme Industries
email: [email protected]
plan: enterprise
createdAt: '2026-05-14T10:05:00Z'
indie:
summary: Indie developer
value:
id: CUST-000143
name: Jane Dev
plan: free
Sandboxes → Mocks → Use Cses → Playgrounds → Testing → Virtualization → Synthetics → Microcks → Examples → OpenAPI → AsyncAPI → MCP → Examples → Business Outcomes → Happy & Unhappy Paths
The Future
Desktop → Web → Mobile → Agents → Automation → Devices → Networks → Pipelines → Known Knowns → Known Unknowns → Unknown Unknowns → Stack → Architecture → Resources → Tools → Capabilities
Enrich the Spec.
Ship the Sandbox.
Let the Agents Learn.
apievangelist.com • github.com/kinlane
Kin Lane • [email protected]
