{
  "openapi": "3.1.1",
  "info": {
    "title": "Amir Pournasserian search API",
    "description": "Hybrid keyword and semantic search over the pages of Amir Pournasserian, and details of the index behind it. The same index is served to AI agents through the MCP endpoint, which is not part of this document.",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://ai.pournasserian.com/"
    }
  ],
  "paths": {
    "/api/search": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "Search the site",
        "description": "Returns the pages that best match the query, ranked by hybrid keyword and semantic search, each with a plain and a highlighted snippet. When the index holds no embeddings, or the query cannot be embedded, the results come from keyword search alone and keywordOnly is true.",
        "operationId": "Search",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "What to look for. Natural language or keywords.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results. Defaults to SearchApi:DefaultLimit and is capped at SearchApi:MaxLimit.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchApiResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests"
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/info": {
      "get": {
        "tags": [
          "Info"
        ],
        "summary": "Describe the server and its index",
        "description": "Returns the site, the loaded index with its build statistics, and the endpoint URLs. Answers 503 with the same shape, and no index, until an index is loaded.",
        "operationId": "Info",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteInfo"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteInfo"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiError": {
        "required": [
          "error"
        ],
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      },
      "EndpointUrls": {
        "required": [
          "mcp",
          "mcpRequiresKey",
          "searchApi",
          "openApi",
          "docs"
        ],
        "type": "object",
        "properties": {
          "mcp": {
            "type": "string"
          },
          "mcpRequiresKey": {
            "type": "boolean"
          },
          "searchApi": {
            "type": [
              "null",
              "string"
            ]
          },
          "openApi": {
            "type": "string"
          },
          "docs": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "IndexStats": {
        "type": "object",
        "properties": {
          "source": {
            "type": [
              "null",
              "string"
            ]
          },
          "startedAt": {
            "type": [
              "null",
              "string"
            ],
            "format": "date-time"
          },
          "durationSeconds": {
            "type": "number",
            "format": "double"
          },
          "pagesFetched": {
            "type": "integer",
            "format": "int32"
          },
          "pagesSkippedNoIndex": {
            "type": "integer",
            "format": "int32"
          },
          "pagesSkippedDuplicate": {
            "type": "integer",
            "format": "int32"
          },
          "pagesSkippedEmpty": {
            "type": "integer",
            "format": "int32"
          },
          "errors": {
            "type": "integer",
            "format": "int32"
          },
          "embeddingsGenerated": {
            "type": "integer",
            "format": "int32"
          },
          "embeddingsFromCache": {
            "type": "integer",
            "format": "int32"
          },
          "words": {
            "type": "integer",
            "format": "int64"
          },
          "newestPageModified": {
            "type": [
              "null",
              "string"
            ],
            "format": "date-time"
          },
          "languages": {
            "type": "object",
            "additionalProperties": {
              "type": "integer",
              "format": "int32"
            }
          },
          "sections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SectionStats"
            }
          }
        }
      },
      "IndexSummary": {
        "required": [
          "builtAt",
          "loadedAt",
          "stale",
          "pageCount",
          "chunkCount",
          "store",
          "formatVersion",
          "keywordOnly",
          "embeddingModel",
          "embeddingDimensions",
          "indexerVersion",
          "stats"
        ],
        "type": "object",
        "properties": {
          "builtAt": {
            "type": "string",
            "format": "date-time"
          },
          "loadedAt": {
            "type": [
              "null",
              "string"
            ],
            "format": "date-time"
          },
          "stale": {
            "type": "boolean"
          },
          "pageCount": {
            "type": "integer",
            "format": "int32"
          },
          "chunkCount": {
            "type": "integer",
            "format": "int32"
          },
          "store": {
            "type": "string"
          },
          "formatVersion": {
            "type": "integer",
            "format": "int32"
          },
          "keywordOnly": {
            "type": "boolean"
          },
          "embeddingModel": {
            "type": [
              "null",
              "string"
            ]
          },
          "embeddingDimensions": {
            "type": "integer",
            "format": "int32"
          },
          "indexerVersion": {
            "type": [
              "null",
              "string"
            ]
          },
          "stats": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/IndexStats"
              }
            ]
          }
        }
      },
      "SearchApiResponse": {
        "required": [
          "query",
          "keywordOnly",
          "results"
        ],
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "keywordOnly": {
            "type": "boolean"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchApiResult"
            }
          }
        }
      },
      "SearchApiResult": {
        "required": [
          "title",
          "url",
          "description",
          "snippet",
          "highlightedSnippet",
          "section",
          "score"
        ],
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "description": {
            "type": [
              "null",
              "string"
            ]
          },
          "snippet": {
            "type": "string"
          },
          "highlightedSnippet": {
            "type": "string"
          },
          "section": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "score": {
            "type": "number",
            "format": "double"
          }
        }
      },
      "SectionStats": {
        "required": [
          "path",
          "title",
          "pages"
        ],
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "title": {
            "type": [
              "null",
              "string"
            ]
          },
          "pages": {
            "type": "integer",
            "format": "int32"
          }
        }
      },
      "ServerSummary": {
        "required": [
          "name",
          "version"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        }
      },
      "SiteInfo": {
        "required": [
          "status",
          "site",
          "index",
          "endpoints",
          "server"
        ],
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "site": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SiteSummary"
              }
            ]
          },
          "index": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/IndexSummary"
              }
            ]
          },
          "endpoints": {
            "$ref": "#/components/schemas/EndpointUrls"
          },
          "server": {
            "$ref": "#/components/schemas/ServerSummary"
          }
        }
      },
      "SiteSummary": {
        "required": [
          "name",
          "url",
          "description",
          "language"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "description": {
            "type": [
              "null",
              "string"
            ]
          },
          "language": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Search"
    },
    {
      "name": "Info"
    }
  ]
}