OpenAPI requirements

Clankerbay reads your OpenAPI document to build CLI commands, MCP tools, search results and gateway routing. The validator enforces these rules.

Supported

• OpenAPI 3.0.0–3.0.4 and 3.1.0–3.1.2, as JSON or YAML, in a single file up to 2 MB.
• Methods GET, POST, PUT, PATCH, DELETE.
• Parameters in path, query and header.
• Request bodies of type application/json, application/x-www-form-urlencoded, text/plain and application/octet-stream.
• Local references ($ref: '#/components/…') and allOf composition.

Rejected

• Swagger 2.0 (convert it first).
• External references ($ref: other-file.yaml): bundle your document into one file.
• Cookie parameters, and header parameters named Authorization, Cookie, Host or X-Clankerbay-*.
• Other request content types, such as multipart/form-data.
• Two operations that map to the same command name, and undeclared path template parameters.

Callbacks, webhooks and HEAD/OPTIONS/TRACE operations are ignored with a warning.

Clankerbay extensions

Example

openapi: 3.1.0
info:
  title: Acme Weather
  version: "2026-10"
servers:
  - url: https://api.acme-weather.example
paths:
  /forecast/{city}:
    get:
      operationId: getForecast
      x-cli-command: forecast
      x-clankerbay-price: 3
      summary: Seven-day forecast for a city
      parameters:
        - name: city
          in: path
          required: true
          schema: { type: string }
        - name: units
          in: query
          schema: { type: string, enum: [metric, imperial], default: metric }
      responses:
        "200":
          description: Forecast
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Forecast" }
components:
  schemas:
    Forecast:
      type: object
      properties:
        days: { type: array, items: { type: object } }

This becomes cb acme-weather forecast Dublin --units imperial.

Versioning

Clients see your schema with servers pointing at the Clankerbay gateway, your security schemes replaced by the Clankerbay token, and info.x-clankerbay-schema-version set. The CLI pins the version it used: if a later version removes a command or adds required inputs, pinned calls are rejected with schema_changed instead of silently misbehaving.