OpenAPI Spec

Weight: 8% of your AX score. This check verifies that /.well-known/openapi.json exists with a valid OpenAPI 3.x specification describing your API endpoints.

openapi.json not found

Create /.well-known/openapi.json with your API specification. Even if your site doesn't have a traditional REST API, you can document any data endpoints:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Your Site API",
    "description": "API providing structured data for Your Site.",
    "version": "1.0.0",
    "contact": {
      "name": "Your Name",
      "url": "https://your-site.com",
      "email": "email@your-site.com"
    }
  },
  "servers": [
    {
      "url": "https://api.your-site.com",
      "description": "Production API"
    }
  ],
  "paths": {
    "/data": {
      "get": {
        "operationId": "getData",
        "summary": "Get all data",
        "description": "Returns structured data.",
        "responses": {
          "200": {
            "description": "Successful response"
          }
        }
      }
    }
  }
}

Quick fix with ax-init

Run npx ax-init and select "OpenAPI Spec" to generate a starter openapi.json based on your site.

Invalid JSON

Your openapi.json has invalid JSON syntax. Validate it with a JSON linter or the Swagger Editor.

Upgrade from Swagger 2.x

Your spec uses Swagger 2.x ("swagger": "2.0"). AI agents work better with OpenAPI 3.x which has improved schema support, better parameter handling, and is the current standard.

Use the Swagger Editor to convert your 2.x spec to 3.x, or change the root field from "swagger" to "openapi" and update the structure accordingly.

No version field

Add "openapi": "3.1.0" to the root of your spec to declare the OpenAPI version.

Missing info.title

Add an info object with a title field. This is the name AI agents will use to identify your API.

"info": {
  "title": "Your API Name",
  "version": "1.0.0"
}

Missing info.description

Add a description field inside info explaining what your API provides and how AI agents can use it. Be specific about data types and use cases.

No paths documented

Add a paths object documenting your API endpoints. Each path should include the HTTP method, operation ID, summary, and response schema. Even one well-documented endpoint is better than none.

No servers defined

Add a servers array with your API base URL so AI agents know where to send requests:

"servers": [
  {
    "url": "https://api.your-site.com",
    "description": "Production API"
  }
]