{
  "openapi": "3.1.0",
  "info": {
    "title": "YEDHEE API",
    "version": "1.1.0",
    "description": "High-performance JAV catalog, search, and HLS stream metadata API (e.g. id=49331 for NGOD-367). Versioned under /api/v1/ with RFC 9457 Problem Details error handling and RateLimit headers.",
    "contact": {
      "name": "YEDHEE Support",
      "email": "support@yedhee.online",
      "url": "https://yedhee.online/developers"
    }
  },
  "servers": [
    {
      "url": "https://yedhee.online",
      "description": "Production API v1"
    }
  ],
  "paths": {
    "/api/v1/videos": {
      "get": {
        "operationId": "listVideos",
        "summary": "List or search JAV videos",
        "description": "Retrieve paginated JAV catalog items, filter by category, or search using + AND syntax.",
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string", "default": "all" } },
          { "name": "search", "in": "query", "schema": { "type": "string", "example": "NGOD-367" } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 24, "maximum": 48 } }
        ],
        "responses": {
          "200": {
            "description": "Successful paginated video catalog response",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/VideoListResponse" } },
              "text/markdown": { "schema": { "type": "string" } }
            }
          },
          "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } },
          "429": { "description": "Rate Limit Exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }
        }
      }
    },
    "/api/v1/videos/{id}": {
      "get": {
        "operationId": "getVideoDetail",
        "summary": "Get video detail and HLS stream URL",
        "description": "Fetch full metadata, HLS master playlist (.m3u8), poster URL, and related videos by post ID.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "49331" } }
        ],
        "responses": {
          "200": {
            "description": "Successful video detail response",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/VideoDetailResponse" } },
              "text/markdown": { "schema": { "type": "string" } }
            }
          },
          "404": { "description": "Video Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }
        }
      }
    },
    "/api/v1/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "List available video categories",
        "description": "Retrieve grouped video categories with item counts.",
        "responses": {
          "200": {
            "description": "Successful categories response",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/CategoryListResponse" } }
            }
          }
        }
      }
    },
    "/api/v1/mcp": {
      "get": {
        "operationId": "getMcpManifest",
        "summary": "Get MCP tool discovery manifest",
        "description": "Returns Model Context Protocol (MCP) serverInfo and available tool definitions.",
        "responses": {
          "200": {
            "description": "MCP capability manifest",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/McpManifest" } }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "VideoItem": {
        "type": "object",
        "required": ["id", "code", "title", "thumbnail"],
        "properties": {
          "id": { "type": "string", "example": "49331" },
          "code": { "type": "string", "example": "NGOD-367" },
          "title": { "type": "string" },
          "duration": { "type": "string", "example": "HD" },
          "badge": { "type": "string", "example": "ซับไทย" },
          "thumbnail": { "type": "string", "format": "uri" },
          "hls_master": { "type": "string", "format": "uri" },
          "embed_url": { "type": "string", "format": "uri" },
          "release_date": { "type": "string", "format": "date" },
          "views": { "type": "integer" }
        }
      },
      "VideoListResponse": {
        "type": "object",
        "required": ["success", "page", "per_page", "total", "videos"],
        "properties": {
          "success": { "type": "boolean" },
          "source": { "type": "string" },
          "category": { "type": "string" },
          "page": { "type": "integer" },
          "per_page": { "type": "integer" },
          "total": { "type": "integer" },
          "total_pages": { "type": "integer" },
          "videos": { "type": "array", "items": { "$ref": "#/components/schemas/VideoItem" } }
        }
      },
      "VideoDetailResponse": {
        "type": "object",
        "required": ["success", "video", "related"],
        "properties": {
          "success": { "type": "boolean" },
          "video": { "$ref": "#/components/schemas/VideoItem" },
          "related": { "type": "array", "items": { "$ref": "#/components/schemas/VideoItem" } }
        }
      },
      "CategoryListResponse": {
        "type": "object",
        "required": ["success", "groups"],
        "properties": {
          "success": { "type": "boolean" },
          "groups": { "type": "array", "items": { "type": "object" } }
        }
      },
      "McpManifest": {
        "type": "object",
        "required": ["protocolVersion", "serverInfo", "tools"],
        "properties": {
          "protocolVersion": { "type": "string", "example": "2024-11-05" },
          "serverInfo": { "type": "object" },
          "tools": { "type": "array", "items": { "type": "object" } }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "required": ["type", "title", "status", "code", "message", "detail"],
        "properties": {
          "type": { "type": "string", "format": "uri" },
          "title": { "type": "string" },
          "status": { "type": "integer" },
          "code": { "type": "string" },
          "message": { "type": "string" },
          "detail": { "type": "string" },
          "resolution": { "type": "string" },
          "instance": { "type": "string" },
          "success": { "type": "boolean", "example": false }
        }
      }
    }
  }
}
