{
  "components": {
    "securitySchemes": {
      "AdminToken": {
        "description": "Admin API token (set in admin panel settings)",
        "in": "header",
        "name": "X-Admin-Token",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "description": "Privacy-respecting meta search for adult video content",
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "title": "VidVeil API",
    "version": "1.0.0"
  },
  "openapi": "3.0.0",
  "paths": {
    "/.well-known/vidveil.json": {
      "get": {
        "description": "Machine-readable server metadata and capability discovery",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "Server metadata"
          }
        },
        "summary": "Well-known metadata"
      }
    },
    "/api/v1/admin/analytics": {
      "get": {
        "description": "Aggregate search analytics — privacy-safe (no per-user data). Requires admin token.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "Analytics summary"
          },
          "401": {
            "description": "Unauthorized"
          }
        },
        "security": [
          {
            "AdminToken": []
          }
        ],
        "summary": "Search analytics"
      }
    },
    "/api/v1/admin/engines/{name}": {
      "patch": {
        "description": "Enable or disable a search engine by name. Requires admin token.",
        "parameters": [
          {
            "description": "Engine name",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "enabled": {
                    "description": "Whether the engine should be enabled",
                    "type": "boolean"
                  }
                },
                "required": [
                  "enabled"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Engine updated"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Engine not found"
          }
        },
        "security": [
          {
            "AdminToken": []
          }
        ],
        "summary": "Toggle engine"
      }
    },
    "/api/v1/admin/engines/{name}/reset": {
      "post": {
        "description": "Manually reset the circuit breaker for a search engine. Requires admin token.",
        "parameters": [
          {
            "description": "Engine name",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Circuit breaker reset"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Engine not found"
          }
        },
        "security": [
          {
            "AdminToken": []
          }
        ],
        "summary": "Reset circuit breaker"
      }
    },
    "/api/v1/engines": {
      "get": {
        "description": "Get all search engines with status and privacy scores",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "array"
                }
              }
            },
            "description": "Engine list with privacy metadata"
          }
        },
        "summary": "List engines"
      }
    },
    "/api/v1/engines/health": {
      "get": {
        "description": "Get health status including circuit breaker state for each engine",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "array"
                }
              }
            },
            "description": "Engine health data"
          }
        },
        "summary": "Engine health"
      }
    },
    "/api/v1/healthz": {
      "get": {
        "description": "Get API health status (per PART 13)",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "Healthy"
          }
        },
        "summary": "Health check"
      }
    },
    "/api/v1/search": {
      "get": {
        "description": "Search across multiple adult video engines",
        "parameters": [
          {
            "description": "Search query (supports bang syntax: !ph, !xv, etc.)",
            "in": "query",
            "name": "q",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Page number (default: 1)",
            "in": "query",
            "name": "page",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Search results with optional spell suggestion"
          }
        },
        "summary": "Search videos"
      }
    },
    "/api/v1/search/batch": {
      "post": {
        "description": "Search multiple queries in one request (max 5 queries)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "queries": {
                    "description": "List of search queries",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 5,
                    "type": "array"
                  }
                },
                "required": [
                  "queries"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "Batch search results"
          }
        },
        "summary": "Batch search"
      }
    },
    "/healthz": {
      "get": {
        "description": "Kubernetes-style health endpoint",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "summary": "Kubernetes health"
      }
    },
    "/search.atom": {
      "get": {
        "description": "Search results as Atom 1.0 feed",
        "parameters": [
          {
            "description": "Search query",
            "in": "query",
            "name": "q",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/atom+xml": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Atom feed"
          }
        },
        "summary": "Atom feed"
      }
    },
    "/search.rss": {
      "get": {
        "description": "Search results as RSS 2.0 feed",
        "parameters": [
          {
            "description": "Search query",
            "in": "query",
            "name": "q",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "RSS feed"
          }
        },
        "summary": "RSS feed"
      }
    }
  },
  "servers": [
    {
      "description": "Current server",
      "url": "/"
    }
  ]
}