OpenAPI Examples and Tags
Are the Missing Link Between
Your APIs and AI Agents
APIDays NYC — OpenAPI Track
Kin Lane • Co-Founder, Naftiko • [email protected]
2026
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
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
Enrichc the Spec.
Ship the Sandbox.
Let the Agents Learn.
github.com/naftiko/sandboxes • naftiko.io
Kin Lane • [email protected]