{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent NAS documentation search",
    "version": "0.2.0",
    "summary": "Search the Agent NAS concept, design and specification.",
    "description": "Full-text search over the pages of agentnas.com. Every result links to the page and to its Markdown version. The same content is also available through the MCP server described at /mcp/server-card.",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://agentnas.com"
    }
  ],
  "paths": {
    "/api/search": {
      "post": {
        "operationId": "search_docs",
        "summary": "Search the documentation",
        "description": "Returns the best matching pages for a query, ranked by relevance, with a short snippet each.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              },
              "example": {
                "query": "capability lease",
                "locale": "en",
                "limit": 5
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Matching pages, best first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "405": {
            "$ref": "#/components/responses/Error"
          },
          "413": {
            "$ref": "#/components/responses/Error"
          },
          "415": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "required": [
          "query"
        ],
        "additionalProperties": false,
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Words or a phrase to look for."
          },
          "locale": {
            "type": "string",
            "enum": [
              "en",
              "zh-cn",
              "zh-tw",
              "ja",
              "ko",
              "es",
              "fr",
              "de"
            ],
            "default": "en",
            "description": "Language of the pages to search."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 5,
            "description": "Maximum number of results."
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": [
          "query",
          "locale",
          "total",
          "results"
        ],
        "properties": {
          "query": {
            "type": "string"
          },
          "locale": {
            "type": "string"
          },
          "total": {
            "type": "integer",
            "description": "Number of pages that matched, before applying the limit."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            }
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "required": [
          "id",
          "title",
          "description",
          "url",
          "markdown_url",
          "snippet",
          "score"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Page id, for example `what-is` or `concept/capability-lease`."
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdown_url": {
            "type": "string",
            "format": "uri"
          },
          "snippet": {
            "type": "string",
            "description": "Plain-text excerpt around the best match."
          },
          "score": {
            "type": "number",
            "description": "Relative relevance; only meaningful within one response."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "The request could not be processed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}