{
  "openapi": "3.1.0",
  "info": {
    "title": "Aevral docs public API",
    "version": "1.0.0",
    "summary": "Search and fetch Aevral customer documentation as markdown or JSON.",
    "description": "Public machine surface for docs.aevral.com. Stable REST uses a major version in the path, starting at `/api/v1/`. Unversioned `/api/agent-search` is an alias of `/api/v1/agent-search` and stays. Backward-compatible fields may be added inside v1. A breaking change requires `/api/v2/`. If a version is retired, responses will carry RFC 8594 `Sunset` and RFC 9745 `Deprecation` headers, and this document will name the retirement date at least 90 days ahead. Unknown `/api/*` paths return HTTP 404 application/json `{error:{code,message,docs}}`. Wrong methods return HTTP 405 with Allow: GET, HEAD, OPTIONS. Search GET responses send RateLimit, RateLimit-Policy, and X-RateLimit-* headers. These endpoints index documentation only. Aevral product keys (`aevr_...`) exist via the console Developer API page; the fuller public product API contract is future-tense until announced.",
    "contact": {
      "name": "Aevral Docs",
      "url": "https://docs.aevral.com/docs/for-ai-agents"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://docs.aevral.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "docs",
      "description": "Public customer documentation. No auth."
    }
  ],
  "security": [],
  "paths": {
    "/api/agent-search": {
      "get": {
        "operationId": "searchDocs",
        "tags": ["docs"],
        "summary": "Search English docs",
        "description": "Keyword search over English public docs titles, descriptions, and bodies. `q` must be at least 2 characters. `limit` defaults to 10.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 2 },
            "description": "Search query."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 },
            "description": "Maximum hits to return."
          }
        ],
        "responses": {
          "200": {
            "description": "Search hits",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DocsSearch" }
              }
            },
            "headers": {
              "RateLimit": { "$ref": "#/components/headers/RateLimit" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/Internal" }
        }
      }
    },
    "/api/v1/agent-search": {
      "get": {
        "operationId": "searchDocsV1",
        "tags": ["docs"],
        "summary": "Search English docs (v1)",
        "description": "Versioned alias of GET /api/agent-search. Same query params, envelope, and errors. New integrations should call this path.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 2 },
            "description": "Search query."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 },
            "description": "Maximum hits to return."
          }
        ],
        "responses": {
          "200": {
            "description": "Search hits",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DocsSearch" }
              }
            },
            "headers": {
              "RateLimit": { "$ref": "#/components/headers/RateLimit" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/Internal" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DocsSearch": {
        "type": "object",
        "additionalProperties": false,
        "required": ["q", "count", "hits"],
        "properties": {
          "q": { "type": "string" },
          "count": { "type": "integer" },
          "hits": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/DocsSearchHit" }
          },
          "note": { "type": "string" }
        }
      },
      "DocsSearchHit": {
        "type": "object",
        "additionalProperties": true,
        "required": ["title", "url"],
        "properties": {
          "title": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "mdUrl": { "type": "string", "format": "uri" },
          "description": { "type": "string" }
        }
      },
      "ApiError": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": ["code", "message", "docs"],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "not_found",
                  "invalid_input",
                  "method_not_allowed",
                  "rate_limited",
                  "internal"
                ]
              },
              "message": { "type": "string" },
              "docs": {
                "type": "string",
                "format": "uri",
                "description": "https://docs.aevral.com/docs/for-ai-agents"
              }
            }
          }
        }
      }
    },
    "headers": {
      "RateLimit": {
        "description": "RFC RateLimit remaining.",
        "schema": { "type": "string" }
      },
      "RateLimitPolicy": {
        "description": "RFC RateLimit-Policy.",
        "schema": { "type": "string" }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid query. GET /api/agent-search returns this when q is shorter than 2 characters. Shape is the historical flat envelope, not ApiError.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": false,
              "required": ["error", "message", "hits"],
              "properties": {
                "error": { "type": "string", "example": "query_too_short" },
                "message": { "type": "string" },
                "hits": { "type": "array", "items": {} }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Unknown /api path.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ApiError" }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "Wrong HTTP method. Search is GET-only.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ApiError" }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ApiError" }
          }
        }
      },
      "Internal": {
        "description": "Unexpected server error.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ApiError" }
          }
        }
      }
    }
  }
}