{
  "openapi": "3.1.0",
  "info": {
    "title": "OrbitSearch API",
    "version": "1.0.0",
    "description": "Agent-ready web, image, and maps search API. Image results include authenticated absolute downloadUrl values that return binary image files."
  },
  "servers": [{ "url": "https://search.rviv.in" }],
  "security": [{ "ApiKeyAuth": [] }, { "ApiKeyQuery": [] }],
  "paths": {
    "/search.json": {
      "get": {
        "operationId": "serpApiSearch",
        "summary": "SerpAPI-compatible search endpoint",
        "description": "Drop-in compatibility endpoint supporting web, image, and maps results with snake_case response fields.",
        "parameters": [
          { "name": "api_key", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Alternative to the X-API-Key header." },
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "engine", "in": "query", "schema": { "type": "string", "enum": ["google", "google_images", "google_maps"], "default": "google" } },
          { "name": "location", "in": "query", "schema": { "type": "string" } },
          { "name": "gl", "in": "query", "schema": { "type": "string", "default": "in" } },
          { "name": "hl", "in": "query", "schema": { "type": "string", "default": "en" } },
          { "name": "google_domain", "in": "query", "schema": { "type": "string", "default": "google.com" } },
          { "name": "num", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } },
          { "name": "start", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 990, "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "SerpAPI-compatible structured results",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/usage": {
      "get": {
        "operationId": "getUsage",
        "summary": "Get success-only usage and quota",
        "responses": {
          "200": {
            "description": "Current key usage",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/account": {
      "get": {
        "operationId": "getAccount",
        "summary": "Get SerpAPI-style account quota information",
        "responses": {
          "200": {
            "description": "Account and remaining searches",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "operationId": "search",
        "summary": "Search the web or find downloadable images",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "engine", "in": "query", "required": false, "schema": { "type": "string", "enum": ["google", "google_images"], "default": "google" } },
          { "name": "num", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } },
          { "name": "location", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Structured results. For google_images, each result contains imageUrl, thumbnailUrl, and an authenticated downloadUrl.",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/api/v1/maps": {
      "get": {
        "operationId": "searchMaps",
        "summary": "Search local businesses and places",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "ll", "in": "query", "required": false, "schema": { "type": "string", "example": "@11.0168,76.9558,15z" } }
        ],
        "responses": {
          "200": {
            "description": "Structured local results",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/api/v1/images/download": {
      "get": {
        "operationId": "downloadImage",
        "summary": "Download an image returned by image search",
        "description": "Agents should call the downloadUrl returned by image search instead of constructing this URL manually.",
        "parameters": [
          { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } },
          { "name": "fallback", "in": "query", "required": false, "schema": { "type": "string", "format": "uri" } }
        ],
        "responses": { "200": { "description": "Binary image attachment", "content": { "image/jpeg": {}, "image/png": {}, "image/webp": {}, "image/gif": {}, "image/avif": {} } } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" },
      "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key" }
    }
  }
}