Guides / openapi spec

How to publish an OpenAPI spec for AI agents

An OpenAPI spec tells AI agents exactly what your API can do. Here is how to create and publish one.

Why OpenAPI matters for agents

An OpenAPI specification is the single most important file for AI agent integration. It tells agents exactly what endpoints exist, what parameters to send, what responses to expect, and how to authenticate.
Without an OpenAPI spec, an agent has to scrape your docs site and guess at your API contract. With one, it can generate type-safe API calls automatically.

Minimal spec template

Start with a minimal OpenAPI 3.0 spec and expand from there:

yaml

openapi: 3.0.3
info:
  title: Your API
  version: "1.0"
  description: |
    Brief description of what your API does.

servers:
  - url: https://api.your-domain.com/v1

paths:
  /items:
    get:
      summary: List items
      description: Returns a paginated list of items.
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        "200":
          description: A list of items
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Item"
                  next_cursor:
                    type: string
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    Item:
      type: object
      properties:
        id:
          type: string
          example: "item_abc123"
        name:
          type: string
          example: "Widget"
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string

  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - ApiKey: []

Where to host it

Publish your spec at a standard path. Serge checks these locations:
/openapi.json or /openapi.yaml (recommended)
/api/openapi.json
/.well-known/openapi.json
/swagger.json (legacy but still common)
The file should be publicly accessible without authentication. Reference it from your llms.txt file.

What makes a good spec

The Serge scanner checks several quality dimensions:
Schema completeness — Every endpoint should have typed request and response schemas, not just type: object
Error responses — Document 4xx and 5xx responses with schemas. Agents need to handle errors gracefully
Examples and descriptions — Add example values to properties and description to every endpoint. This helps agents understand intent, not just structure
Security schemes — Document how to authenticate. Without this, agents cannot make authenticated requests

Tools to help

Swagger Editor (editor.swagger.io) — Visual editor for OpenAPI specs
Redocly CLI — Lint and validate your spec: npx @redocly/cli lint openapi.yaml
Fern / Speakeasy — Generate specs from your code, or generate SDKs from your spec
Stoplight Studio — Visual API design tool with OpenAPI export

Check your score

After implementing this, scan your domain to verify the check passes and see how your score changes.

Scan your domain