{
  "openapi": "3.1.0",
  "info": {
    "title": "Vitna Search API",
    "version": "1.0.0",
    "summary": "Low-latency hybrid web index search, similarity search, SERP retrieval, grounded research, and structured extraction.",
    "contact": {
      "name": "Vitna",
      "url": "https://vitna.ai/start#search"
    }
  },
  "externalDocs": {
    "description": "Search documentation",
    "url": "https://vitna.ai/docs/search/overview.md"
  },
  "servers": [
    {
      "url": "https://search.vitna.ai",
      "description": "Hosted Vitna Search API"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "vitna_search_ or vitna_key_"
      }
    }
  },
  "paths": {
    "/healthz": {
      "get": {
        "summary": "Service liveness check",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/readyz": {
      "get": {
        "summary": "Service index readiness probe",
        "security": [],
        "responses": {
          "200": {
            "description": "Ready"
          },
          "503": {
            "description": "Unavailable"
          }
        }
      }
    },
    "/v1/search": {
      "post": {
        "summary": "Query Vitna's web index, vertical indexes, or hybrid external providers",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string"
                  },
                  "index": {
                    "type": "string"
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "index",
                      "live",
                      "auto",
                      "serp",
                      "google"
                    ]
                  },
                  "effort": {
                    "type": "string",
                    "enum": [
                      "fast",
                      "balanced",
                      "deep"
                    ]
                  },
                  "asOf": {
                    "type": "string"
                  },
                  "maxResults": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 5
                  },
                  "domains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "excludeDomains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "contents": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON search response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid search request"
          },
          "401": {
            "description": "Missing or invalid bearer key"
          }
        }
      }
    },
    "/v1/indexes": {
      "get": {
        "summary": "List Vitna's web and vertical search indexes with readiness and document counts",
        "responses": {
          "200": {
            "description": "Index catalog"
          }
        }
      }
    },
    "/v1/indexes/counts": {
      "get": {
        "summary": "Read cached aggregate document counts across Vitna's web and vertical search indexes",
        "security": [],
        "responses": {
          "200": {
            "description": "Cached index document counts"
          },
          "503": {
            "description": "Index counts unavailable"
          }
        }
      }
    },
    "/v1/similar": {
      "post": {
        "summary": "Find pages semantically and lexically similar to a URL",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "maxResults": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON search response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid search request"
          },
          "401": {
            "description": "Missing or invalid bearer key"
          }
        }
      }
    },
    "/v1/serp": {
      "get": {
        "summary": "Retrieve structured Google or Bing SERP results via query parameters",
        "responses": {
          "200": {
            "description": "SERP result"
          }
        }
      },
      "post": {
        "summary": "Retrieve structured Google or Bing SERP results",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string"
                  },
                  "engine": {
                    "type": "string",
                    "enum": [
                      "google",
                      "bing"
                    ]
                  },
                  "extras": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON search response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid search request"
          },
          "401": {
            "description": "Missing or invalid bearer key"
          }
        }
      }
    },
    "/v1/serp/bing": {
      "post": {
        "summary": "Retrieve structured Bing SERP results",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON search response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid search request"
          },
          "401": {
            "description": "Missing or invalid bearer key"
          }
        }
      }
    },
    "/v1/serp/jobs": {
      "post": {
        "summary": "Submit a batch SERP collection job",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON search response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid search request"
          },
          "401": {
            "description": "Missing or invalid bearer key"
          }
        }
      }
    },
    "/v1/serp/jobs/{id}": {
      "get": {
        "summary": "Read SERP collection job status",
        "responses": {
          "200": {
            "description": "Job state"
          }
        }
      },
      "delete": {
        "summary": "Cancel a SERP collection job",
        "responses": {
          "202": {
            "description": "Cancelled"
          }
        }
      }
    },
    "/v1/extract": {
      "post": {
        "summary": "Extract structured answers from matching pages",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON search response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid search request"
          },
          "401": {
            "description": "Missing or invalid bearer key"
          }
        }
      }
    },
    "/v1/research": {
      "post": {
        "summary": "Synthesize cited grounded research from retrieved passages",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON search response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid search request"
          },
          "401": {
            "description": "Missing or invalid bearer key"
          }
        }
      }
    },
    "/v1/search/jobs/{id}": {
      "get": {
        "summary": "Read background coverage expansion job progress",
        "responses": {
          "200": {
            "description": "Job state"
          }
        }
      }
    },
    "/v1/status": {
      "get": {
        "summary": "Read search index counts, quotas, and configured verticals",
        "responses": {
          "200": {
            "description": "Status"
          }
        }
      }
    }
  },
  "x-vitna-discovery": {
    "llmsTxt": "https://search.vitna.ai/llms.txt",
    "webMcp": "https://web.vitna.ai/v1/mcp",
    "llmsFullTxt": "https://vitna.ai/llms-full.txt",
    "playground": "https://vitna.ai/search"
  }
}
